# @ohos.multimedia.audio (音频管理)(系统接口)
音频管理提供管理音频的一些基础能力，包括对音频音量、音频设备的管理，以及对音频数据的采集和渲染等。
该模块提供以下音频相关的常用功能：
- [AudioManager](#audiomanager)：音频管理。
- [TonePlayer](#toneplayer9)：用于管理和播放DTMF（Dual Tone Multi Frequency，双音多频）音调，如拨号音、通话回铃音等。
> **说明：**
>
> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.multimedia.audio (音频管理)](arkts-apis-audio.md)。
## 导入模块
```ts
import { audio } from '@kit.AudioKit';
```
## 常量
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
| 名称 | 类型 | 只读 | 说明 |
| --------------------------------------- | ----------| ---- | ------------------ |
| LOCAL_NETWORK_ID9+ | string | 是 | 本地设备网络id。 |
## audio.createTonePlayer9+
createTonePlayer(options: AudioRendererInfo, callback: AsyncCallback<TonePlayer>): void
创建DTMF播放器。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Tone
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------------- | ---- | -------------- |
| options | [AudioRendererInfo](arkts-apis-audio-i.md#audiorendererinfo8) | 是 | 配置音频渲染器信息。|
| callback | AsyncCallback<[TonePlayer](#toneplayer9)> | 是 | 回调函数。当获取DTMF播放器成功，err为undefined，data为获取到的DTMF播放器对象；否则为错误对象。|
**示例：**
```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>
创建DTMF播放器。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Tone
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :------ | :---------------------------------------------| :--- | :----------- |
| options | [AudioRendererInfo](arkts-apis-audio-i.md#audiorendererinfo8) | 是 | 配置音频渲染器信息。 |
**返回值：**
| 类型 | 说明 |
| ----------------------------------------- | -------------------------------- |
| Promise<[TonePlayer](#toneplayer9)> | Promise对象，返回DTMF播放器对象。 |
**示例：**
```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
获取ASR处理控制器
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :------ | :---------------------------------------------| :--- |:---------|
| audioCapturer | [AudioCapturer](arkts-apis-audio-AudioCapturer.md) | 是 | 音频采集器对象。 |
**返回值：**
| 类型 | 说明 |
|-------------------------------------------------------| ------------ |
| [AsrProcessingController](#asrprocessingcontroller12) | ASR处理控制器对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
|---------|------------------------------------------|
| 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. |
**示例：**
```ts
import { audio } from '@kit.AudioKit';
let audioStreamInfo: audio.AudioStreamInfo = {
samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000,
channels: audio.AudioChannel.CHANNEL_2,
sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
};
let audioCapturerInfo: audio.AudioCapturerInfo = {
source: audio.SourceType.SOURCE_TYPE_MIC,
capturerFlags: 0
};
let audioCapturerOptions: audio.AudioCapturerOptions = {
streamInfo: audioStreamInfo,
capturerInfo: audioCapturerInfo
};
audio.createAudioCapturer(audioCapturerOptions, (err, data) => {
if (err) {
console.error(`AudioCapturer Created : Error: ${err}`);
} else {
console.info('AudioCapturer Created : Success : SUCCESS');
let audioCapturer = data;
let asrProcessingController = audio.createAsrProcessingController(audioCapturer);
console.info('AsrProcessingController Created : Success : SUCCESS');
}
});
```
## AudioVolumeType
枚举，音频流类型。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
| 名称 | 值 | 说明 |
| ---------------------------- | ------ | ---------- |
| SYSTEM20+ | 6 | 系统音。|
| ULTRASONIC10+ | 10 | 超声波。|
| ALL9+ | 100 | 所有公共音频流。|
## InterruptRequestResultType9+
枚举，音频中断请求结果类型。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Interrupt
| 名称 | 值 | 说明 |
| ---------------------------- | ------ | ---------- |
| INTERRUPT_REQUEST_GRANT | 0 | 请求音频中断成功。 |
| INTERRUPT_REQUEST_REJECT | 1 | 请求音频中断失败，可能具有较高优先级类型。 |
## DeviceFlag
枚举，可获取的设备种类。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
| 名称 | 值 | 说明 |
| ------------------------------- | ------ |---------------------------|
| NONE_DEVICES_FLAG9+ | 0 | 无设备。 |
| DISTRIBUTED_OUTPUT_DEVICES_FLAG9+ | 4 | 分布式输出设备。 |
| DISTRIBUTED_INPUT_DEVICES_FLAG9+ | 8 | 分布式输入设备。 |
| ALL_DISTRIBUTED_DEVICES_FLAG9+ | 12 | 分布式输入和输出设备。 |
## EffectFlag18+
枚举，音效分类。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Core
| 名称 | 值 | 说明 |
| ------------------------------- | ------ |------------------------------|
| RENDER_EFFECT_FLAG | 0 | 下行音效类型。 |
| CAPTURE_EFFECT_FLAG | 1 | 上行音效类型。 |
## AudioEffectProperty18+
音效属性。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Core
| 名称 | 类型 | 只读 | 可选 | 说明 |
| ------------------ | ---- | ---- |---| --------- |
| name | string | 否 | 否 | 音效名称。 |
| category | string | 否 | 否 | 音效分类。 |
| flag | [EffectFlag](#effectflag18) | 否 | 否 | 音效分类。 |
## StreamUsage
枚举，音频流使用类型。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Core
| 名称 | 值 | 说明 |
| ------------------------------------------| ------ |-----------------------------|
| STREAM_USAGE_SYSTEM10+ | 9 | 系统音(如屏幕锁定或按键音)。 |
| STREAM_USAGE_DTMF10+ | 14 | 拨号音。 |
| STREAM_USAGE_ENFORCED_TONE10+ | 15 | 强制音(如相机快门音)。 |
| STREAM_USAGE_ULTRASONIC10+ | 16 | 超声波（目前仅提供给MSDP使用）。 |
| STREAM_USAGE_VOICE_CALL_ASSISTANT12+ | 21 | 通话辅助语音。 |
## InterruptRequestType9+
枚举，音频中断请求类型。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Interrupt
| 名称 | 值 | 说明 |
| ---------------------------------- | ------ | ------------------------- |
| INTERRUPT_REQUEST_TYPE_DEFAULT | 0 | 默认类型，可中断音频请求。 |
## VolumeFlag12+
枚举，音量相关操作。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
| 名称 | 值 | 说明 |
| ---------------------------------- |---|----------|
| FLAG_SHOW_SYSTEM_UI | 1 | 拉起系统音量条。 |
## AsrNoiseSuppressionMode12+
枚举，ASR 噪音抑制模式
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
| 名称| 值 | 说明 |
|-------|-------|-------|
| BYPASS | 0 |旁路噪音抑制。|
| STANDARD | 1 |标准噪音抑制。|
| NEAR_FIELD | 2 |近场噪音抑制。|
| FAR_FIELD | 3 |远场噪音抑制。|
## AsrAecMode12+
枚举，ASR AEC 模式
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
| 名称| 值 | 说明 |
|-------|-------|-------|
| BYPASS | 0 |BYPASS AEC|
| STANDARD | 1 |STANDARD AEC|
## AsrWhisperDetectionMode12+
枚举，ASR（Automatic Speech Recognition，自动语音识别）耳语检测模式。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
| 名称 | 值 | 说明 |
|-----|---|----------|
| BYPASS | 0 | 不启用检测模型。 |
| STANDARD | 1 | 耳语检测模型。 |
## AsrVoiceControlMode12+
枚举，ASR音频通路模式。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
| 名称 | 值 | 说明 |
|-------------------------|---|---------------------------------------|
| AUDIO_2_VOICE_TX | 0 | 仅媒体音频流生效。 |
| AUDIO_MIX_2_VOICE_TX | 1 | 媒体音频流和MIC音频流均生效。 |
| AUDIO_2_VOICE_TX_EX | 2 | 仅媒体音频流生效，将媒体流上报给通话录音。 |
| AUDIO_MIX_2_VOICE_TX_EX | 3 | 媒体音频流和MIC音频流均生效，将媒体流上报给通话录音。 |
## AsrVoiceMuteMode12+
枚举，ASR静音模式。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
| 名称 | 值 | 说明 |
|----------------|---|---------------------|
| OUTPUT_MUTE | 0 | 本地输出静音。 |
| INPUT_MUTE | 1 | 本地的MIC输入静音。 |
| TTS_MUTE | 2 | 应用下发的媒体音频本地静音。 |
| CALL_MUTE | 3 | 通话语音流静音。 |
| OUTPUT_MUTE_EX | 4 | 本地输出静音，媒体音频流送给通话录音。 |
## InterruptResult9+
音频中断结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Interrupt
| 名称 | 类型 | 只读 | 可选 | 说明 |
| --------------| -------------------------------------------------------------- | ---- |---| ---------------- |
| requestResult | [InterruptRequestResultType](#interruptrequestresulttype9) | 否 | 否 | 表示音频请求中断类型。 |
| interruptNode | number | 否 | 否 | 音频请求中断的节点。 |
## VolumeEvent9+
音量改变时，应用接收的事件。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
| 名称 | 类型 | 只读 | 可选 | 说明 |
| ---------- | ----------------------------------- | ---- |---|-------------------------------------------|
| volumeGroupId | number | 否 | 否 | 音量组id，可用于getGroupManager入参。 |
| networkId | string | 否 | 否 | 网络id。 |
## ConnectType9+
枚举，设备连接类型。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
| 名称 | 值 | 说明 |
| :------------------------------ | :----- | :--------------------- |
| CONNECT_TYPE_LOCAL | 1 | 本地设备。 |
| CONNECT_TYPE_DISTRIBUTED | 2 | 分布式设备。 |
## VolumeGroupInfos9+
音量组信息，数组类型，为[VolumeGroupInfo](#volumegroupinfo9)的数组，只读。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
## VolumeGroupInfo9+
音量组信息。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
| 名称 | 类型 | 只读 | 可选 | 说明 |
| -------------------------- | -------------------------- | ---- | ---- | ---------- |
| networkId9+ | string | 是 | 否 | 组网络id。 |
| groupId9+ | number | 是 | 否 | 组设备组id。 |
| mappingId9+ | number | 是 | 否 | 组映射id。 |
| groupName9+ | string | 是 | 否 | 组名。 |
| type9+ | [ConnectType](#connecttype9)| 是 | 否 | 连接设备类型。 |
## SourceType8+
枚举，音源类型。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Core
| 名称 | 值 | 说明 |
| :------------------------------------------- | :----- | :--------------------- |
| SOURCE_TYPE_WAKEUP 10+ | 3 | 语音唤醒音频流录制音频源。
**需要权限：** ohos.permission.MANAGE_INTELLIGENT_VOICE |
| SOURCE_TYPE_VOICE_CALL11+ | 4 | 通话录音的音频源。
**需要权限：** ohos.permission.RECORD_VOICE_CALL |
| SOURCE_TYPE_VOICE_TRANSCRIPTION18+ | 12 | 语音转写音频源。 |
## VolumeAdjustType10+
枚举，音量调节类型。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
| 名称 | 值 | 说明 |
| :--------------------- | :----- | :-------------------------------------------- |
| VOLUME_UP | 0 | 向上调节音量。 |
| VOLUME_DOWN | 1 | 向下调节音量。 |
## AudioManager
管理音频音量和音频设备。在调用AudioManager的接口前，需要先通过[getAudioManager](arkts-apis-audio-f.md#audiogetaudiomanager)创建实例。
### setExtraParameters11+
setExtraParameters(mainKey: string, kvpairs: Record): Promise<void>
音频扩展参数设置。使用Promise异步回调。
**需要权限：** ohos.permission.MODIFY_AUDIO_SETTINGS
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------------- |
| mainKey | string | 是 | 被设置的音频参数的主键。 |
| kvpairs | Record | 是 | 被设置的音频参数的子键值对。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ------------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
|-----|------------------------------------------------------------------------------------------------------------|
| 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. |
**示例：**
```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\>
获取指定音频参数值。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ |--| ---------------------- |
| mainKey | string | 是 | 待获取的音频参数的主键。 |
| subKeys | Array\ | 否 | 待获取的音频参数的子键。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | ----------------------------------- |
| Promise\> | Promise对象，返回获取的音频参数的值。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------ | -------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```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
设置音频场景模式。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Communication
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :------- | :----------------------------------- | :--- | :------------------- |
| scene | [AudioScene](arkts-apis-audio-e.md#audioscene8) | 是 | 音频场景模式。 |
| callback | AsyncCallback | 是 | 回调函数。当设置音频场景模式成功，err为undefined，否则为错误对象。 |
**示例：**
```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
设置音频场景模式。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Communication
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :----- | :----------------------------------- | :--- | :------------- |
| scene | [AudioScene](arkts-apis-audio-e.md#audioscene8) | 是 | 音频场景模式。 |
**返回值：**
| 类型 | 说明 |
| :------------- | :------------------- |
| Promise | Promise对象。无返回结果的Promise对象。 |
**示例：**
```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}`);
});
```
### getEffectManager18+
getEffectManager(): AudioEffectManager
获取音效会话管理器。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Core
**返回值：**
| 类型 | 说明 |
|----------------------------------------------| ----------------------------- |
| [AudioEffectManager](#audioeffectmanager18) | AudioEffectManager实例。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
**示例：**
```ts
import { audio } from '@kit.AudioKit';
let audioEffectManager: audio.AudioEffectManager = audioManager.getEffectManager();
```
### disableSafeMediaVolume12+
disableSafeMediaVolume(): Promise<void>
设置安全音量为非激活状态。使用Promise异步回调。
设置为非激活状态后，当设备长时间高音量播放时，不再自动提醒用户降低到安全音量。
**需要权限：** ohos.permission.MODIFY_AUDIO_SETTINGS
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Core
**返回值：**
| 类型 | 说明 |
|------------------------------------------| ----------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
**示例：**
```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
> **说明：**
> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用AudioVolumeManager中的[on('volumeChange')](arkts-apis-audio-AudioVolumeManager.md#onvolumechangedeprecated)替代。
监听系统音量变化事件（当系统音量发生变化时触发）。使用callback异步回调。
目前此订阅接口在单进程多AudioManager实例的使用场景下，仅最后一个实例的订阅生效，其他实例的订阅会被覆盖（即使最后一个实例没有进行订阅），因此推荐使用单一AudioManager实例进行开发。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型，支持的事件为'volumeChange'，当系统音量发生变化时，触发该事件。 |
| callback | Callback<[VolumeEvent](#volumeevent9)> | 是 | 回调函数，返回变化后的音量信息。 |
**示例：**
```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
监听铃声模式变化事件（当[铃声模式](arkts-apis-audio-e.md#audioringmode)发生改变时触发）。使用callback异步回调。
> **说明：**
> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用AudioVolumeGroupManager中的[on('ringerModeChange')](arkts-apis-audio-AudioVolumeGroupManager.md#onringermodechange9)替代。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Communication
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型，支持的事件为'ringerModeChange'，当铃声模式发生改变时，触发该事件。 |
| callback | Callback<[AudioRingMode](arkts-apis-audio-e.md#audioringmode)> | 是 | 回调函数，返回变化后的铃音模式。 |
**示例：**
```ts
audioManager.on('ringerModeChange', (ringerMode: audio.AudioRingMode) => {
console.info(`Updated ringermode: ${ringerMode}`);
});
```
## forceVolumeKeyControlType20+
forceVolumeKeyControlType(volumeType: AudioVolumeType, duration: number): void
设置音量键调节类型。
**需要权限：** ohos.permission.MODIFY_AUDIO_SETTINGS
**系统接口：** 此接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ |
| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 应用程序期望控制的音量类型。 |
| duration |number | 是 | 无音量键事件时，控制音量类型的持续时间。当计时器到期时，强制音量类型设置将被取消，最大持续时间不得超过10秒。如果持续时间设置为-1，则取消该设置。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
| 6800101 | Parameter verification failed. |
| 6800301 | Crash or blocking occurs in system process. |
**示例：**
```ts
import { audio } from '@kit.AudioKit';
let audioManager = audio.getAudioManager();
let audioVolumeManager = audioManager.getVolumeManager();
// 设置音量保持类型为响铃模式。
let volumeType = audio.AudioVolumeType.RINGTONE;
let duration = 10;
audioVolumeManager.forceVolumeKeyControlType(volumeType, duration);
// 取消音量保持类型，恢复默认音量控制。
let volumeTypeDefault = audio.AudioVolumeType.MEDIA;
let durationToCancel = -1;
audioVolumeManager.forceVolumeKeyControlType(volumeTypeDefault, durationToCancel);
```
## AudioVolumeManager9+
音量管理。在使用AudioVolumeManager的接口前，需要使用[getVolumeManager](arkts-apis-audio-AudioManager.md#getvolumemanager9)获取AudioVolumeManager实例。
### getVolumeGroupInfos9+
getVolumeGroupInfos(networkId: string, callback: AsyncCallback\): void
获取音量组信息列表。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------------------------------------------------ | ---- | -------------------- |
| networkId | string | 是 | 设备的网络id。本地设备audio.LOCAL_NETWORK_ID。 |
| callback | AsyncCallback<[VolumeGroupInfos](#volumegroupinfos9)> | 是 | 回调函数。当获取音量组信息列表成功，err为undefined，data为获取到的音量组信息列表；否则为错误对象。 |
**示例：**
```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
获取音量组信息列表。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------| ---- | -------------------- |
| networkId | string | 是 | 设备的网络id。本地设备audio.LOCAL_NETWORK_ID。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ----------------------------- |
| Promise<[VolumeGroupInfos](#volumegroupinfos9)> | Promise对象，返回音量组信息列表。 |
**示例：**
```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
获取音量组信息列表，同步返回结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------| ---- | -------------------- |
| networkId | string | 是 | 设备的网络id。本地设备audio.LOCAL_NETWORK_ID。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ----------------------------- |
| [VolumeGroupInfos](#volumegroupinfos9) | 音量组信息列表。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```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}`);
}
```
### getAppVolumePercentageForUid19+
getAppVolumePercentageForUid(uid: number\): Promise
根据应用ID获取指定应用的音量（范围为0到100）。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ---------------------------------------- | ---- |----------------------------------|
| uid | number | 是 | 表示应用ID。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ----------------------------- |
| Promise<number> | Promise对象，返回应用的音量（范围为0到100）。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
| 6800101 | Parameter verification failed.|
**示例：**
```ts
let uid: number = 20010041; // 应用ID。
audioVolumeManager.getAppVolumePercentageForUid(20010041).then((value: number) => {
console.info(`app volume is ${value}.`);
});
```
### setAppVolumePercentageForUid19+
setAppVolumePercentageForUid(uid: number, volume: number\): Promise
根据应用ID设置指定应用的音量（范围为0到100）。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ---------------------------------------- | ---- |----------|
| uid | number | 是 | 表示应用ID。 |
| volume | number | 是 | 要设置的音量值。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ------------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
| 6800101 | Parameter verification failed.|
| 6800301 | Crash or blocking occurs in system process. |
**示例：**
```ts
let uid: number = 20010041; // 应用ID。
let volume: number = 20; // 要设置的音量值。
audioVolumeManager.setAppVolumePercentageForUid(uid, volume).then(() => {
console.info(`set app volume success.`);
});
```
### isAppVolumeMutedForUid19+
isAppVolumeMutedForUid(uid: number, owned: boolean\): Promise
根据应用ID查询应用音量是否已静音。使用Promise异步回调。
> **说明：**
>
> 如果有多个调用者设置了静音状态，那么只有当所有调用者都取消静音状态后，此应用才会真正取消静音。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ---------------------------------------- | ---- |-------------------------------------------|
| uid | number | 是 | 表示应用ID。 |
| owned | boolean | 是 | 要查询的静音状态。true查询当前调用者的静音状态，false查询应用的静音状态。 |
**返回值：**
| 类型 | 说明 |
| ------------------- |---------------------|
| Promise<boolean> | Promise对象。返回true表示应用为静音状态；返回false表示应用为非静音状态。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
| 6800101 | Parameter verification failed.|
**示例：**
```ts
let uid: number = 20010041; // 应用ID。
audioVolumeManager.isAppVolumeMutedForUid(uid, true).then((value: boolean) => {
console.info(`app muted state is ${value}.`);
});
```
### setAppVolumeMutedForUid19+
setAppVolumeMutedForUid(uid: number, muted: boolean\): Promise
根据应用ID设置应用静音状态。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ---------------------------------------- | ---- |--------------------------------|
| uid | number | 是 | 表示应用ID。 |
| owned | boolean | 是 | 设置应用的静音状态。true设置为静音，false解除静音。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ------------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
| 6800101 | Parameter verification failed.|
| 6800301 | Crash or blocking occurs in system process. |
**示例：**
```ts
let uid: number = 20010041; // 应用ID。
audioVolumeManager.setAppVolumeMutedForUid(uid, true).then(() => {
console.info(`set app mute state success.`);
});
```
### on('appVolumeChangeForUid')19+
on(type: 'appVolumeChangeForUid', uid: number, callback: Callback\): void
监听指定应用应用级音量变化事件（当应用级音量发生变化时触发）。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------------- | ---- |-----------------------------------|
| type | string | 是 | 事件回调类型，支持的事件为'appVolumeChangeForUid'，当应用级音量发生变化时，触发该事件。 |
| uid | number | 是 | 表示应用ID。 |
| callback | Callback<[VolumeEvent](arkts-apis-audio-i.md#volumeevent9)> | 是 | 回调函数，返回变化后的音量信息。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
let uid: number = 20010041; // 应用ID。
audioVolumeManager.on('appVolumeChangeForUid', uid, (volumeEvent: audio.VolumeEvent) => {
console.info(`VolumeType of stream: ${volumeEvent.volumeType} `);
console.info(`Volume level: ${volumeEvent.volume} `);
console.info(`Whether to updateUI: ${volumeEvent.updateUi} `);
});
```
### off('appVolumeChangeForUid')19+
off(type: 'appVolumeChangeForUid', callback?: Callback\): void
取消监听指定应用应用级音量变化事件。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型，支持的事件为'appVolumeChangeForUid'，当取消监听指定应用应用级音量变化事件时，触发该事件。 |
| callback | Callback<[VolumeEvent](arkts-apis-audio-i.md#volumeevent9)> | 否 | 回调函数，返回变化后的音量信息。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
// 取消该事件的所有监听。
audioVolumeManager.off('appVolumeChangeForUid');
// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。
let appVolumeChangeForUidCallback = (volumeEvent: audio.VolumeEvent) => {
console.info(`VolumeType of stream: ${volumeEvent.volumeType} `);
console.info(`Volume level: ${volumeEvent.volume} `);
console.info(`Whether to updateUI: ${volumeEvent.updateUi} `);
};
audioVolumeManager.on('appVolumeChangeForUid', appVolumeChangeForUidCallback);
audioVolumeManager.off('appVolumeChangeForUid', appVolumeChangeForUidCallback);
```
### on('activeVolumeTypeChange')20+
on(type: 'activeVolumeTypeChange', callback: Callback\): void
监听当前活跃流变化事件（当活跃流发生变化时触发）。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型，支持的事件为'activeVolumeTypeChange'，当活跃流发生变化时，触发该事件。 |
| callback | Callback\<[AudioVolumeType](arkts-apis-audio-e.md#audiovolumetype)> | 是 | 回调函数，返回变化后的活跃流类型。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
audioVolumeManager.on('activeVolumeTypeChange', (volumeType: audio.AudioVolumeType) => {
console.info(`VolumeType of stream: ${volumeType} `);
});
```
### off('activeVolumeTypeChange')20+
off(type: 'activeVolumeTypeChange', callback?: Callback\): void
取消监听当前活跃流变化事件。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型，支持的事件为'activeVolumeTypeChange'，当取消监听当前活跃流变化事件时，触发该事件。 |
| callback | Callback\<[AudioVolumeType](arkts-apis-audio-e.md#audiovolumetype)> | 否 | 回调函数，返回变化后的活跃流类型。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
// 取消该事件的所有监听。
audioVolumeManager.off('activeVolumeTypeChange');
// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。
let activeVolumeTypeChangeCallback = (volumeType: audio.AudioVolumeType) => {
console.info(`VolumeType of stream: ${volumeType} `);
};
audioVolumeManager.on('activeVolumeTypeChange', activeVolumeTypeChangeCallback);
audioVolumeManager.off('activeVolumeTypeChange', activeVolumeTypeChangeCallback);
```
## AudioVolumeGroupManager9+
管理音频组音量。在调用AudioVolumeGroupManager的接口前，需要先通过 [getVolumeGroupManager](arkts-apis-audio-AudioVolumeManager.md#getvolumegroupmanager9) 创建实例。
### setVolume9+
setVolume(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback<void>): void
设置指定流的音量。使用callback异步回调。
**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY
仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 |
| volume | number | 是 | 音量等级，可设置范围通过[getMinVolume](arkts-apis-audio-AudioVolumeGroupManager.md#getminvolumedeprecated)和[getMaxVolume](arkts-apis-audio-AudioVolumeGroupManager.md#getmaxvolumedeprecated)获取。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当设置指定流的音量成功，err为undefined，否则为错误对象。 |
**示例：**
```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>
设置指定流的音量。使用Promise异步回调。
**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY
仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 |
| volume | number | 是 | 音量等级，可设置范围通过[getMinVolume](arkts-apis-audio-AudioVolumeGroupManager.md#getminvolumedeprecated)和[getMaxVolume](arkts-apis-audio-AudioVolumeGroupManager.md#getmaxvolumedeprecated)获取。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ----------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**示例：**
```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>
设置指定流的音量，同时指定本次修改音量是否要显示系统音量条。使用Promise异步回调。
**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY
仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ----------------------------------- | ---- |--------------------------------------|
| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 |
| volume | number | 是 | 音量等级，可设置范围通过[getMinVolume](arkts-apis-audio-AudioVolumeGroupManager.md#getminvolumedeprecated)和[getMaxVolume](arkts-apis-audio-AudioVolumeGroupManager.md#getmaxvolumedeprecated)获取。 |
| flags | number | 是 | 是否需要显示系统音量条，0为不需要显示，1为需要显示。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ----------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Not system App. |
**示例：**
```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
设置指定音量流静音。使用callback异步回调。
**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY
仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ----------------------------------- | ---- | ------------------------------------- |
| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 |
| mute | boolean | 是 | 静音状态，true为静音，false为非静音。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当设置指定音量流静音成功，err为undefined，否则为错误对象。 |
**示例：**
```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>
设置指定音量流静音。使用Promise异步回调。
**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY
仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ----------------------------------- | ---- | ------------------------------------- |
| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 |
| mute | boolean | 是 | 静音状态，true为静音，false为非静音。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ----------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**示例：**
```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
设置铃声模式。使用callback异步回调。
**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY
仅在静音和非静音状态切换时需要该权限。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------- | ---- | ------------------------ |
| mode | [AudioRingMode](arkts-apis-audio-e.md#audioringmode) | 是 | 音频铃声模式。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当设置铃声模式成功，err为undefined，否则为错误对象。 |
**示例：**
```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>
设置铃声模式。使用Promise异步回调。
**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY
仅在静音和非静音状态切换时需要该权限。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------------- | ---- | -------------- |
| mode | [AudioRingMode](arkts-apis-audio-e.md#audioringmode) | 是 | 音频铃声模式。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ------------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**示例：**
```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>
设置麦克风静音状态。使用Promise异步回调。
**需要权限：** ohos.permission.MANAGE_AUDIO_CONFIG
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------- | ---- | --------------------------------------------- |
| mute | boolean | 是 | 待设置的静音状态，true为静音，false为非静音。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ------------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 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. |
**示例：**
```ts
audioVolumeGroupManager.setMicMute(true).then(() => {
console.info('Promise returned to indicate that the mic is muted.');
});
```
### adjustVolumeByStep10+
adjustVolumeByStep(adjustType: VolumeAdjustType, callback: AsyncCallback<void>): void
调节当前最高优先级的流的音量，使音量值按步长加或减。使用callback异步回调。
**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY
仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| adjustType | [VolumeAdjustType](#volumeadjusttype10) | 是 | 音量调节方向。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当调节当前最高优先级的流的音量成功，err为undefined，否则为错误对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 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. |
**示例：**
```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>
单步设置当前最高优先级的流的音量。使用Promise异步回调。
**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY
仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| adjustType | [VolumeAdjustType](#volumeadjusttype10) | 是 | 音量调节方向。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ----------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 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. |
**示例：**
```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
单步设置指定流的音量。使用callback异步回调。
**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY
仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 |
| adjustType | [VolumeAdjustType](#volumeadjusttype10) | 是 | 音量调节方向。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当单步设置指定流的音量成功，err为undefined，否则为错误对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 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. |
**示例：**
```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>
单步设置指定流的音量。使用Promise异步回调。
**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY
仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Volume
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- |
| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 |
| adjustType | [VolumeAdjustType](#volumeadjusttype10) | 是 | 音量调节方向。 |
**返回值：**
| 类型 | 说明 |
| ------------------- | ----------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| -------- | --------------------------------------------|
| 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. |
**示例：**
```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.');
});
```
## AudioEffectManager18+
音频效果管理。在使用AudioEffectManager的接口前，需要使用[getEffectManager](#geteffectmanager18)获取AudioEffectManager实例。
### getSupportedAudioEffectProperty18+
getSupportedAudioEffectProperty(): Array\
获取支持的下行音效模式，同步返回结果。
**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Core
**返回值：**
| 类型 | 说明 |
| --------------------------------------------------------------------------| --------------------------------------- |
| Array\<[AudioEffectProperty](#audioeffectproperty18)> | 返回当前设备支持的音效模式。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Caller is not a system application. |
| 6800301 | System error. Return by callback. |
**示例：**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let propertyArray: Array = audioStreamManager.getSupportedAudioEffectProperty();
console.info(`The effect modes are: ${propertyArray}`);
} catch (err) {
let error = err as BusinessError;
console.error(`getSupportedAudioEffectProperty ERROR: ${error}`);
}
```
### getAudioEffectProperty18+
getAudioEffectProperty(): Array\
获取当前音效模式，同步返回结果。
**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Core
**返回值：**
| 类型 | 说明 |
| --------------------------------------------------------------------------| --------------------------------------- |
| Array\<[AudioEffectProperty](#audioeffectproperty18)> | 返回当前音效模式。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Caller is not a system application. |
| 6800301 | System error. Return by callback. |
**示例：**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let propertyArray: Array = audioStreamManager.getAudioEffectProperty();
console.info(`The effect modes are: ${propertyArray}`);
} catch (err) {
let error = err as BusinessError;
console.error(`getAudioEffectProperty ERROR: ${error}`);
}
```
### setAudioEffectProperty18+
setAudioEffectProperty(propertyArray: Array\): void
设置当前音效模式，同步返回结果。
**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.core
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ------------- | ----------------------------------------------------- | -------- | ---------------------------- |
| propertyArray | Array\<[AudioEffectProperty](#audioeffectproperty18)> | 是 | 需要设置的音效模式。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. |
| 202 | Caller is not a system application. |
| 6800101 | Parameter verification failed. Possible causes: 1.more than one enhanceProps of the same enhanceClass in input Array; 2.input audioEnhanceProperties are not supported by current device. 3.names of enhanceProp or enhanceClass are incorrect.|
| 6800301 | System error. Return by callback. |
**示例：**
```ts
import { BusinessError } from '@kit.BasicServicesKit';
try {
let propertyArray: Array = audioEffectManager.getAudioEffectProperty();
console.info(`The effect modes are: ${propertyArray}`);
audioEffectManager.setAudioEffectProperty(propertyArray);
} catch (err) {
let error = err as BusinessError;
console.error(`setAudioEffectProperty ERROR: ${error}`);
}
```
## AudioRoutingManager9+
音频路由管理。在使用AudioRoutingManager的接口前，需要使用[getRoutingManager](arkts-apis-audio-AudioManager.md#getroutingmanager9)获取AudioRoutingManager实例。
### selectInputDevice9+
selectInputDevice(inputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void
选择音频输入设备，当前只能选择一个输入设备。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| inputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输入设备类。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当选择音频输入设备成功，err为undefined，否则为错误对象。 |
**示例：**
```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>
选择音频输入设备，当前只能选择一个输入设备。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| inputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输入设备类。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**示例：**
```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
选择音频输出设备，当前只能选择一个输出设备。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| outputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输出设备类。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当选择音频输出设备成功，err为undefined，否则为错误对象。 |
**示例：**
```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>
选择音频输出设备，当前只能选择一个输出设备。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| outputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输出设备类。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**示例：**
```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
根据过滤条件，选择音频输出设备，当前只能选择一个输出设备。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| filter | [AudioRendererFilter](#audiorendererfilter9) | 是 | 过滤条件类。 |
| outputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输出设备类。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当选择音频输出设备成功，err为undefined，否则为错误对象。 |
**示例：**
```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>
根据过滤条件，选择音频输出设备，当前只能选择一个输出设备。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| filter | [AudioRendererFilter](#audiorendererfilter9) | 是 | 过滤条件类。 |
| outputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输出设备类。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**示例：**
```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}`);
})
}
```
### selectInputDeviceByFilter18+
selectInputDeviceByFilter(filter: AudioCapturerFilter, inputAudioDevices: AudioDeviceDescriptors): Promise<void>
根据过滤条件，选择音频输入设备，当前只能选择一个输入设备。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------------------|-------------------------------------------------------------------| ---- |--------|
| filter | [AudioCapturerFilter](#audiocapturerfilter18) | 是 | 过滤条件类。 |
| inputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输入设备类。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 6800101 | Parameter verification failed.|
**示例：**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let inputAudioCapturerFilter: audio.AudioCapturerFilter = {
uid : 20010041,
capturerInfo : {
source: audio.SourceType.SOURCE_TYPE_MIC,
capturerFlags: 0
}
};
let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
deviceRole : audio.DeviceRole.INPUT_DEVICE,
deviceType : audio.DeviceType.MIC,
id : 1,
name : "",
address : "",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : "",
}];
async function selectInputDeviceByFilter(){
let audioManager = audio.getAudioManager(); // 需要先创建AudioManager实例。
let audioRoutingManager = audioManager.getRoutingManager(); // 再调用AudioManager的方法创建AudioRoutingManager实例。
audioRoutingManager.selectInputDeviceByFilter(inputAudioCapturerFilter, inputAudioDeviceDescriptor).then(() => {
console.info('Select input devices by filter result promise: SUCCESS');
}).catch((err: BusinessError) => {
console.error(`Result ERROR: ${err}`);
})
}
```
### getPreferredOutputDeviceByFilter18+
getPreferredOutputDeviceByFilter(filter: AudioRendererFilter): AudioDeviceDescriptors
根据过滤条件，查询音频输出设备。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| filter | [AudioRendererFilter](#audiorendererfilter9) | 是 | 过滤条件类。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors)| return the device list. |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 6800101 | Parameter verification failed.|
**示例：**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let outputAudioRendererFilter: audio.AudioRendererFilter = {
uid : 20010041,
rendererInfo : {
usage : audio.StreamUsage.STREAM_USAGE_MUSIC,
rendererFlags : 0
},
rendererId : 0
};
async function selectOutputDeviceByFilter(){
let audioManager = audio.getAudioManager(); // 需要先创建AudioManager实例。
let audioRoutingManager = audioManager.getRoutingManager(); // 再调用AudioManager的方法创建AudioRoutingManager实例。
let desc : audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredOutputDeviceByFilter(outputAudioRendererFilter);
console.info(`device descriptor: ${desc}`);
}
```
### getPreferredInputDeviceByFilter18+
getPreferredInputDeviceByFilter(filter: AudioCapturerFilter): AudioDeviceDescriptors
根据过滤条件，查询音频输入设备，当前只能查询一个输入设备。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
|---------------------|-----------------------------------------------| ---- | ------------------------- |
| filter | [AudioCapturerFilter](#audiocapturerfilter18) | 是 | 过滤条件类。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | return the device list. |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 6800101 | Parameter verification failed.|
**示例：**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let inputAudioCapturerFilter: audio.AudioCapturerFilter = {
uid : 20010041,
capturerInfo : {
source: audio.SourceType.SOURCE_TYPE_MIC,
capturerFlags: 0
}
};
async function getPreferredInputDeviceByFilter(){
let audioManager = audio.getAudioManager(); // 需要先创建AudioManager实例。
let audioRoutingManager = audioManager.getRoutingManager(); // 再调用AudioManager的方法创建AudioRoutingManager实例。
let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredInputDeviceByFilter(inputAudioCapturerFilter);
console.info(`device descriptor: ${desc}`);
}
```
### excludeOutputDevices18+
excludeOutputDevices(usage: DeviceUsage, devices: AudioDeviceDescriptors): Promise<void>
排除输出设备。成功调用此函数后，音频将不会在指定的设备上播放。
> **说明：**
>
> 该功能仅能排除外部输出设备，不支持本地输出设备。
**需要权限：** ohos.permission.MANAGE_AUDIO_CONFIG
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| usage | [DeviceUsage](arkts-apis-audio-e.md#deviceusage12) | 是 | 设备种类。只支持排除输出设备。 |
| devices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 排除输出设备列表。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| Promise<void> | Promise对象。无返回结果。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. Return by callback. |
| 202 | Not system App. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let usage: audio.DeviceUsage.MEDIA_OUTPUT_DEVICES;
let excludedDevices: audio.AudioDeviceDescriptors = [{
deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
deviceType : audio.DeviceType.BLUETOOTH_A2DP,
id : 3,
name : "",
address : "",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : "",
}];
async function excludeOutputDevices(){
audioRoutingManager.excludeOutputDevices(usage, excludedDevices, (err: BusinessError) => {
if (err) {
console.error(`Result ERROR: ${err}`);
} else {
console.info('Exclude Output Devices result callback: SUCCESS'); }
});
}
```
### unexcludeOutputDevices18+
unexcludeOutputDevices(usage: DeviceUsage, devices: AudioDeviceDescriptors): Promise<void>
解除排除输出设备。成功调用此函数后，音频将会重新选择输出设备。
**需要权限：** ohos.permission.MANAGE_AUDIO_CONFIG
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| usage | [DeviceUsage](arkts-apis-audio-e.md#deviceusage12) | 是 | 设备种类。只支持排除输出设备。 |
| devices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 解除排除输出设备列表。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| Promise<void> | Promise对象。无返回结果。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. Return by callback. |
| 202 | Not system App. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let usage: audio.DeviceUsage.MEDIA_OUTPUT_DEVICES;
let unexcludedDevices: audio.AudioDeviceDescriptors = [{
deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
deviceType : audio.DeviceType.BLUETOOTH_A2DP,
id : 3,
name : "",
address : "",
sampleRates : [44100],
channelCounts : [2],
channelMasks : [0],
networkId : audio.LOCAL_NETWORK_ID,
interruptGroupId : 1,
volumeGroupId : 1,
displayName : "",
}];
async function unexcludeOutputDevices(){
audioRoutingManager.unexcludeOutputDevices(usage, unexcludedDevices, (err: BusinessError) => {
if (err) {
console.error(`Result ERROR: ${err}`);
} else {
console.info('Unexclude Output Devices result callback: SUCCESS'); }
});
}
```
### unexcludeOutputDevices18+
unexcludeOutputDevices(usage: DeviceUsage): Promise<void>
解除属于特定用途的所有输出设备的排除。成功调用此函数后，音频将会重新选择输出设备。
**需要权限：** ohos.permission.MANAGE_AUDIO_CONFIG
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| usage | [DeviceUsage](arkts-apis-audio-e.md#deviceusage12) | 是 | 设备种类。只支持排除输出设备。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| Promise<void> | Promise对象。无返回结果。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. Return by callback. |
| 202 | Not system App. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';
let usage: audio.DeviceUsage.MEDIA_OUTPUT_DEVICES;
async function unexcludeOutputDevices(){
audioRoutingManager.unexcludeOutputDevices(usage).then(() => {
console.info('Unexclude Output Devices result promise: SUCCESS');
}).catch((err: BusinessError) => {
console.error(`Result ERROR: ${err}`);
});
}
```
### getExcludedDevices18+
getExcludedDevices(usage: DeviceUsage): AudioDeviceDescriptors
获取排除输出设备列表。
**需要权限：** ohos.permission.MANAGE_AUDIO_CONFIG
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Device
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| usage | [DeviceUsage](arkts-apis-audio-e.md#deviceusage12) | 是 | 设备种类。只支持排除输出设备。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 排除设备列表。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 201 | Permission denied. Return by callback. |
| 202 | Not system App. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
import { audio } from '@kit.AudioKit';
let usage: audio.DeviceUsage.MEDIA_OUTPUT_DEVICES;
async function getExcludedDevices(){
let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getExcludedDevices(usage);
console.info(`device descriptor: ${desc}`);
}
```
## AudioRendererChangeInfo9+
描述音频渲染器更改信息。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Renderer
| 名称 | 类型 | 只读 | 可选 | 说明 |
| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- |
| clientUid | number | 是 | 否 | 音频渲染器客户端应用程序的Uid。 |
| rendererState | [AudioState](arkts-apis-audio-e.md#audiostate8) | 是 | 否 | 音频状态。|
## AudioCapturerChangeInfo9+
描述音频采集器更改信息。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
| 名称 | 类型 | 只读 | 可选 | 说明 |
| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- |
| clientUid | number | 是 | 否 | 音频采集器客户端应用程序的Uid。 |
| capturerState | [AudioState](arkts-apis-audio-e.md#audiostate8) | 是 | 否 | 音频状态。|
## AudioDeviceDescriptor
描述音频设备。
**系统接口：** 该接口为系统接口。
| 名称 | 类型 | 只读 | 可选 | 说明 |
| ----------------------------- | -------------------------- | ---- | ---- | ---------- |
| networkId9+ | string | 是 | 否 | 设备组网的ID。
**系统能力：** SystemCapability.Multimedia.Audio.Device|
| interruptGroupId9+ | number | 是 | 否 | 设备所处的焦点组ID。
**系统能力：** SystemCapability.Multimedia.Audio.Device|
| volumeGroupId9+ | number | 是 | 否 | 设备所处的音量组ID。
**系统能力：** SystemCapability.Multimedia.Audio.Device|
| dmDeviceType18+ | number | 是 | 是 | 设备的子类型ID。
**系统能力：** SystemCapability.Multimedia.Audio.Core|
## AudioRendererFilter9+
过滤条件类。在调用selectOutputDeviceByFilter接口前，需要先创建AudioRendererFilter实例。
**系统接口：** 该接口为系统接口。
| 名称 | 类型 | 只读 | 可选 | 说明 |
| -------------| ---------------------------------------- | ---- |---| -------------- |
| uid | number | 否 | 是 | 表示应用ID。
**系统能力：** SystemCapability.Multimedia.Audio.Core|
| rendererInfo | [AudioRendererInfo](arkts-apis-audio-i.md#audiorendererinfo8) | 否 | 是 | 表示渲染器信息。
**系统能力：** SystemCapability.Multimedia.Audio.Renderer|
| rendererId | number | 否 | 是 | 音频流唯一id。
**系统能力：** SystemCapability.Multimedia.Audio.Renderer|
**示例：**
```ts
import { audio } from '@kit.AudioKit';
let outputAudioRendererFilter: audio.AudioRendererFilter = {
uid : 20010041,
rendererInfo : {
usage : audio.StreamUsage.STREAM_USAGE_MUSIC,
rendererFlags : 0
},
rendererId : 0
};
```
## AudioCapturerFilter18+
过滤条件类。在调用selectOutputDeviceByFilter接口前，需要先创建AudioCapturerFilter实例。
**系统接口：** 该接口为系统接口。
| 名称 | 类型 | 只读 | 可选 | 说明 |
| -------------| ---------------------------------------- | ---- |---| -------------- |
| uid | number | 否 | 是 | 表示应用ID。
**系统能力：** SystemCapability.Multimedia.Audio.Core|
| capturerInfo | [AudioCapturerInfo](arkts-apis-audio-i.md#audiocapturerinfo8) | 否 | 是 | 表示采集器信息。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer|
**示例：**
```ts
import { audio } from '@kit.AudioKit';
let inputAudioCapturerFilter: audio.AudioCapturerFilter = {
uid : 20010041,
capturerInfo : {
source: audio.SourceType.SOURCE_TYPE_MIC,
capturerFlags: 0
}
};
```
## AudioSpatialEnabledStateForDevice12+
监听设备空间音频开关状态。
**系统接口**：此接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
| 参数名 | 类型 | 只读 | 可选 | 说明 |
| ----------------------| ------------------------------------------------------------ | ---- |---| ------------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 否 | 否 | 指定设备的描述。 |
| enabled | boolean | 否 | 否 | 表示开启/关闭空间音频渲染或头动。true为开启，false为关闭。 |
## AudioSpatializationManager11+
空间音频管理。在使用AudioSpatializationManager的接口前，需要使用[getSpatializationManager](arkts-apis-audio-AudioManager.md#getspatializationmanager18)获取AudioSpatializationManager实例。
### isSpatializationSupported11+
isSpatializationSupported(): boolean
获取系统是否支持空间音频，同步返回结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**返回值：**
| 类型 | 说明 |
| ---------------------- | ------------------------------------------------------------ |
| boolean | 返回系统是否支持空间音频，true为支持，false为不支持。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
**示例：**
```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
获取指定设备是否支持空间音频，同步返回结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------------------------------------------------ | ---- | -------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 是 | 指定设备的描述。 |
**返回值：**
| 类型 | 说明 |
| ---------------------- | ------------------------------------------------------------ |
| boolean | 返回指定设备是否支持空间音频，true为支持，false为不支持。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```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
获取系统是否支持头动跟踪，同步返回结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**返回值：**
| 类型 | 说明 |
| ---------------------- | ------------------------------------------------------------ |
| boolean | 返回系统是否支持头动跟踪，true为支持，false为不支持。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
**示例：**
```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
获取指定设备是否支持头动跟踪，同步返回结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ---------- | ------------------------------------------------------------ | ---- | -------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 是 | 指定设备的描述。 |
**返回值：**
| 类型 | 说明 |
| ---------------------- | ------------------------------------------------------------ |
| boolean | 返回指定设备是否支持头动跟踪，true为支持，false为不支持。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```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
根据输入指令，开启/关闭空间音频渲染效果。使用callback异步回调。
> **说明：**
> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\](#setspatializationenabled12)替代。
**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| enable | boolean | 是 | 表示开启/关闭空间音频渲染。true为开启，false为关闭。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当开启/关闭空间音频渲染效果成功，err为undefined，否则为错误对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 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. |
**示例：**
```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>
根据输入指令，开启/关闭空间音频渲染效果。使用Promise异步回调。
> **说明：**
> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\](#setspatializationenabled12)替代。
**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| enable | boolean | 是 | 表示开启/关闭空间音频渲染。true为开启，false为关闭。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 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. |
**示例：**
```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>
根据输入指令，开启/关闭指定设备的空间音频渲染效果。使用Promise异步回调。
**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 是 | 指定设备的描述。 |
| enabled | boolean | 是 | 表示开启/关闭空间音频渲染。true为开启，false为关闭。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 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. |
**示例：**
```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
获取空间音频渲染是否开启，同步返回结果。
> **说明：**
> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[isSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean](#isspatializationenabled12)替代。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**返回值：**
| 类型 | 说明 |
| ---------------------- | ------------------------------------------------------------ |
| boolean | 返回空间音频渲染是否开启，true为开启，false为未开启。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
**示例：**
```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
获取指定设备的空间音频渲染是否开启，同步返回结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 是 | 指定设备的描述。 |
**返回值：**
| 类型 | 说明 |
| ---------------------- | ------------------------------------------------------------ |
| boolean | 返回指定设备的空间音频渲染是否开启，true为开启，false为未开启。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```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
监听空间音频渲染开关状态变化事件（当空间音频渲染开关状态发生变化时触发）。使用callback异步回调。
> **说明：**
> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[on(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback): void](#onspatializationenabledchangeforanydevice12)替代。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------|
| type | string | 是 | 事件回调类型，支持的事件为'spatializationEnabledChange'，当空间音频渲染开关状态发生变化时，触发该事件。 |
| callback | Callback | 是 | 回调函数。返回true表示音频渲染已打开；返回false表示音频渲染已关闭。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
import { audio } from '@kit.AudioKit';
audioSpatializationManager.on('spatializationEnabledChange', (isSpatializationEnabled: boolean) => {
console.info(`isSpatializationEnabled: ${isSpatializationEnabled}`);
});
```
### on('spatializationEnabledChangeForAnyDevice')12+
on(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback): void
监听空间音频渲染开关状态变化事件（当空间音频渲染开关状态发生变化时触发）。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------|
| type | string | 是 | 事件回调类型，支持的事件为'spatializationEnabledChangeForAnyDevice'，当空间音频渲染开关状态发生变化时，触发该事件。 |
| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | 是 | 回调函数，返回设备信息和空间音频渲染开关状态。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```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
取消监听空间音频渲染开关状态变化事件。使用callback异步回调。
> **说明：**
> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[off(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback): void](#offspatializationenabledchangeforanydevice12)替代。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------------------- | ---- | ------------------------------------------ |
| type | string | 是 | 事件回调类型，支持的事件为'spatializationEnabledChange'，当取消监听空间音频渲染开关状态变化事件时，触发该事件。 |
| callback | Callback | 否 | 回调函数。返回true表示音频渲染已打开；返回false表示音频渲染已关闭。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
// 取消该事件的所有监听。
audioSpatializationManager.off('spatializationEnabledChange');
// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。
let spatializationEnabledChangeCallback = (isSpatializationEnabled: boolean) => {
console.info(`isSpatializationEnabled: ${isSpatializationEnabled}`);
};
audioSpatializationManager.on('spatializationEnabledChange', spatializationEnabledChangeCallback);
audioSpatializationManager.off('spatializationEnabledChange', spatializationEnabledChangeCallback);
```
### off('spatializationEnabledChangeForAnyDevice')12+
off(type: 'spatializationEnabledChangeForAnyDevice', callback?: Callback): void
取消监听空间音频渲染开关状态变化事件。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------|
| type | string | 是 | 事件回调类型，支持的事件为'spatializationEnabledChangeForAnyDevice'，当取消监听空间音频渲染开关状态变化事件时，触发该事件。 |
| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | 是 | 回调函数，返回设备信息和空间音频渲染开关状态。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
import { audio } from '@kit.AudioKit';
// 取消该事件的所有监听。
audioSpatializationManager.off('spatializationEnabledChangeForAnyDevice');
// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。
let spatializationEnabledChangeForAnyDeviceCallback = (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => {
console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`);
console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`);
};
audioSpatializationManager.on('spatializationEnabledChangeForAnyDevice', spatializationEnabledChangeForAnyDeviceCallback);
audioSpatializationManager.off('spatializationEnabledChangeForAnyDevice', spatializationEnabledChangeForAnyDeviceCallback);
```
### setHeadTrackingEnabled(deprecated)
setHeadTrackingEnabled(enable: boolean, callback: AsyncCallback<void>): void
根据输入指令，开启/关闭头动跟踪效果。使用callback异步回调。
> **说明：**
> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[setHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\](#setheadtrackingenabled12)替代。
**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- |
| enable | boolean | 是 | 表示开启/关闭头动跟踪。true为开启，false为关闭。 |
| callback | AsyncCallback<void> | 是 | 回调函数。当开启/关闭头动跟踪效果成功，err为undefined，否则为错误对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 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. |
**示例：**
```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>
根据输入指令，开启/关闭头动跟踪效果。使用Promise异步回调。
> **说明：**
> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[setHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\](#setheadtrackingenabled12)替代。
**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| enable | boolean | 是 | 表示开启/关闭头动跟踪。true为开启，false为关闭。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 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. |
**示例：**
```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>
根据输入指令，开启/关闭指定设备的头动跟踪效果。使用Promise异步回调。
**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 是 | 指定设备的描述。 |
| enable | boolean | 是 | 表示开启/关闭头动跟踪。true为开启，false为关闭。 |
**返回值：**
| 类型 | 说明 |
| --------------------- | --------------------------- |
| Promise<void> | Promise对象。无返回结果的Promise对象。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 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. |
**示例：**
```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
获取头动跟踪是否开启，同步返回结果。
> **说明：**
> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[isHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean](#isheadtrackingenabled12)替代。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**返回值：**
| 类型 | 说明 |
| ---------------------- | ------------------------------------------------------------ |
| boolean | 返回头动跟踪是否开启，true为开启，false为未开启。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
**示例：**
```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(deviceDescriptor: AudioDeviceDescriptor): boolean
获取指定设备的头动跟踪是否开启，同步返回结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- |
| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 是 | 指定设备的描述。 |
**返回值：**
| 类型 | 说明 |
| ---------------------- | ------------------------------------------------------------ |
| boolean | 返回指定设备的头动跟踪是否开启，true为开启，false为未开启。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```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
监听头动跟踪开关状态变化事件（当动跟踪开关状态发生变化时触发）。使用callback异步回调。
> **说明：**
> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[on(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback): void](#onheadtrackingenabledchangeforanydevice12)替代。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- |
| type | string | 是 | 事件回调类型，支持的事件为'headTrackingEnabledChange'，当动跟踪开关状态发生变化时，触发该事件。 |
| callback | Callback | 是 | 回调函数。返回true表示头动跟踪已打开；返回false表示头动跟踪已关闭。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
import { audio } from '@kit.AudioKit';
audioSpatializationManager.on('headTrackingEnabledChange', (isHeadTrackingEnabled: boolean) => {
console.info(`isHeadTrackingEnabled: ${isHeadTrackingEnabled}`);
});
```
### on('headTrackingEnabledChangeForAnyDevice')12+
on(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback): void
监听头动跟踪开关状态变化事件（当动跟踪开关状态发生变化时触发）。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- |
| type | string | 是 | 事件回调类型，支持的事件为'headTrackingEnabledChangeForAnyDevice'，当动跟踪开关状态发生变化时，触发该事件。 |
| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | 是 | 回调函数。返回true表示头动跟踪已打开；返回false表示头动跟踪已关闭。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```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
取消监听头动跟踪开关状态变化事件。使用callback异步回调。
> **说明：**
> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[off(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback): void](#offheadtrackingenabledchangeforanydevice12)替代。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------------------- | ---- | ------------------------------------------ |
| type | string | 是 | 事件回调类型，支持的事件为'headTrackingEnabledChange'，当取消监听头动跟踪开关状态变化事件时，触发该事件。 |
| callback | Callback | 否 | 回调函数。返回true表示头动跟踪已打开；返回false表示头动跟踪已关闭。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
import { audio } from '@kit.AudioKit';
// 取消该事件的所有监听。
audioSpatializationManager.off('headTrackingEnabledChange');
// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。
let headTrackingEnabledChangeCallback = (isHeadTrackingEnabled: boolean) => {
console.info(`isHeadTrackingEnabled: ${isHeadTrackingEnabled}`);
};
audioSpatializationManager.on('headTrackingEnabledChange', headTrackingEnabledChangeCallback);
audioSpatializationManager.off('headTrackingEnabledChange', headTrackingEnabledChangeCallback);
```
### off('headTrackingEnabledChangeForAnyDevice')12+
off(type: 'headTrackingEnabledChangeForAnyDevice', callback?: Callback): void
取消监听头动跟踪开关状态变化事件。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------------------- | ---- | ------------------------------------------ |
| type | string | 是 | 事件回调类型，支持的事件为'headTrackingEnabledChangeForAnyDevice'，当取消监听头动跟踪开关状态变化事件时，触发该事件。 |
| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | 是 | 回调函数。返回true表示头动跟踪已打开；返回false表示头动跟踪已关闭。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
| 6800101 | Parameter verification failed. |
**示例：**
```ts
import { audio } from '@kit.AudioKit';
// 取消该事件的所有监听。
audioSpatializationManager.off('headTrackingEnabledChangeForAnyDevice');
// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。
let headTrackingEnabledChangeForAnyDeviceCallback = (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => {
console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`);
console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`);
};
audioSpatializationManager.on('headTrackingEnabledChangeForAnyDevice', headTrackingEnabledChangeForAnyDeviceCallback);
audioSpatializationManager.off('headTrackingEnabledChangeForAnyDevice', headTrackingEnabledChangeForAnyDeviceCallback);
```
### updateSpatialDeviceState11+
updateSpatialDeviceState(spatialDeviceState: AudioSpatialDeviceState): void
更新空间化设备状态，同步返回结果。
**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------------------- | ---- | ------------------------------------------ |
| spatialDeviceState | [AudioSpatialDeviceState](#audiospatialdevicestate11) | 是 | 需要更新的空间化设备状态。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 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. |
**示例：**
```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
设置空间音频渲染场景类型，同步返回结果。
**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------------------- | ---- | ------------------------------------------ |
| spatializationSceneType | [AudioSpatializationSceneType](#audiospatializationscenetype12) | 是 | 需要设置的空间音频渲染场景类型。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 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. |
**示例：**
```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
查询当前空间音频渲染场景类型，同步返回结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
**返回值：**
| 类型 | 说明 |
| ---------------------- | ------------------------------------------------------------ |
| [AudioSpatializationSceneType](#audiospatializationscenetype12) | 返回当前空间音频渲染场景类型。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。
| 错误码ID | 错误信息 |
| ------- | --------------------------------------------|
| 202 | Not system App. |
**示例：**
```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+
空间化设备状态。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
| 名称 | 类型 | 只读 | 可选 | 说明 |
| ----------------------------- | -------------------------- | ---- | ---- | ---------- |
| address | string | 否 | 否 | 空间化设备地址。|
| isSpatializationSupported | boolean | 否 | 否 | 空间化设备是否支持空间音频渲染。true表示支持，false表示不支持。|
| isHeadTrackingSupported | boolean | 否 | 否 | 空间化设备是否支持头动跟踪。true表示支持，false表示不支持。|
| spatialDeviceType | [AudioSpatialDeviceType](#audiospatialdevicetype11) | 否 | 否 | 空间化设备类型。|
**示例：**
```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+
枚举，空间化设备类型。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
| 名称 | 值 | 说明 |
| ---------------------------------- | ------ | ------------------------- |
| SPATIAL_DEVICE_TYPE_NONE | 0 | 无空间化设备类型。 |
| SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE | 1 | 入耳式耳机。 |
| SPATIAL_DEVICE_TYPE_HALF_IN_EAR_HEADPHONE | 2 | 半入耳式耳机。 |
| SPATIAL_DEVICE_TYPE_OVER_EAR_HEADPHONE | 3 | 头戴式耳机。 |
| SPATIAL_DEVICE_TYPE_GLASSES | 4 | 眼镜式耳机。 |
| SPATIAL_DEVICE_TYPE_OTHERS | 5 | 其他空间化设备类型。|
## AudioSpatializationSceneType12+
枚举，空间音频渲染场景类型。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Spatialization
| 名称 | 值 | 说明 |
| ---------------------------------- | ------ | ------------------------- |
| DEFAULT | 0 | 空间音频默认渲染场景。 |
| MUSIC | 1 | 空间音频音乐渲染场景。 |
| MOVIE | 2 | 空间音频电影渲染场景。 |
| AUDIOBOOK | 3 | 空间音频有声读物渲染场景。 |
## ToneType9+
枚举，播放器的音调类型。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Tone
| 名称 | 值 | 说明 |
| :------------------------------------------------ | :----- | :----------------------------|
| TONE_TYPE_DIAL_0 | 0 | 键0的DTMF音。 |
| TONE_TYPE_DIAL_1 | 1 | 键1的DTMF音。 |
| TONE_TYPE_DIAL_2 | 2 | 键2的DTMF音。 |
| TONE_TYPE_DIAL_3 | 3 | 键3的DTMF音。 |
| TONE_TYPE_DIAL_4 | 4 | 键4的DTMF音。 |
| TONE_TYPE_DIAL_5 | 5 | 键5的DTMF音。 |
| TONE_TYPE_DIAL_6 | 6 | 键6的DTMF音。 |
| TONE_TYPE_DIAL_7 | 7 | 键7的DTMF音。 |
| TONE_TYPE_DIAL_8 | 8 | 键8的DTMF音。 |
| TONE_TYPE_DIAL_9 | 9 | 键9的DTMF音。 |
| TONE_TYPE_DIAL_S | 10 | 键*的DTMF音。 |
| TONE_TYPE_DIAL_P | 11 | 键#的DTMF音。 |
| TONE_TYPE_DIAL_A | 12 | 键A的DTMF音。 |
| TONE_TYPE_DIAL_B | 13 | 键B的DTMF音。 |
| TONE_TYPE_DIAL_C | 14 | 键C的DTMF音。 |
| TONE_TYPE_DIAL_D | 15 | 键D的DTMF音。 |
| TONE_TYPE_COMMON_SUPERVISORY_DIAL | 100 | 呼叫监管音调，拨号音。 |
| TONE_TYPE_COMMON_SUPERVISORY_BUSY | 101 | 呼叫监管音调，忙。 |
| TONE_TYPE_COMMON_SUPERVISORY_CONGESTION | 102 | 呼叫监管音调，拥塞。 |
| TONE_TYPE_COMMON_SUPERVISORY_RADIO_ACK | 103 | 呼叫监管音调，无线电 ACK。 |
| TONE_TYPE_COMMON_SUPERVISORY_RADIO_NOT_AVAILABLE | 104 | 呼叫监管音调，无线电不可用。 |
| TONE_TYPE_COMMON_SUPERVISORY_CALL_WAITING | 106 | 呼叫监管音调，呼叫等待。 |
| TONE_TYPE_COMMON_SUPERVISORY_RINGTONE | 107 | 呼叫监管音调，铃声。 |
| TONE_TYPE_COMMON_SUPERVISORY_CALL_HOLDING18+ | 108 | 呼叫保持音调。 |
| TONE_TYPE_COMMON_PROPRIETARY_BEEP | 200 | 专有声调，一般蜂鸣声。 |
| TONE_TYPE_COMMON_PROPRIETARY_ACK | 201 | 专有声调，ACK。 |
| TONE_TYPE_COMMON_PROPRIETARY_PROMPT | 203 | 专有声调，PROMPT。 |
| TONE_TYPE_COMMON_PROPRIETARY_DOUBLE_BEEP | 204 | 专有声调，双重蜂鸣声。 |
## TonePlayer9+
提供播放和管理DTMF（Dual Tone Multi Frequency，双音多频）音调的方法，包括各种系统监听音调、专有音调，如拨号音、通话回铃音等。
在调用TonePlayer的接口前，需要先通过[createTonePlayer](#audiocreatetoneplayer9)创建实例。
**系统接口：** 该接口为系统接口。
### load9+
load(type: ToneType, callback: AsyncCallback<void>): void
加载DTMF音调配置。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Tone
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :--------------| :-------------------------- | :-----| :------------------------------ |
| type | [ToneType](#tonetype9) | 是 | 配置的音调类型。 |
| callback | AsyncCallback | 是 | 回调函数。当加载DTMF音调配置成功，err为undefined，否则为错误对象。 |
**示例：**
```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>
加载DTMF音调配置。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Tone
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :------------- | :--------------------- | :--- | ---------------- |
| type | [ToneType](#tonetype9) | 是 | 配置的音调类型。 |
**返回值：**
| 类型 | 说明 |
| :--------------| :-------------------------- |
| Promise | Promise对象。无返回结果的Promise对象。 |
**示例：**
```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
启动DTMF音调播放。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Tone
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :------- | :------------------- | :--- | :----------------------------- |
| callback | AsyncCallback | 是 | 回调函数。当启动DTMF音调播放成功，err为undefined，否则为错误对象。 |
**示例：**
```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>
启动DTMF音调播放。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Tone
**返回值：**
| 类型 | 说明 |
| :------------- | :---------------------------- |
| Promise | Promise对象。无返回结果的Promise对象。 |
**示例：**
```ts
tonePlayer.start().then(() => {
console.info('promise call start');
}).catch(() => {
console.error('promise call start fail');
});
```
### stop9+
stop(callback: AsyncCallback<void>): void
停止当前正在播放的音调。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Tone
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :------- | :------------------- | :--- | :----------------------------- |
| callback | AsyncCallback | 是 | 回调函数。当停止当前正在播放的音调成功，err为undefined，否则为错误对象。 |
**示例：**
```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>
停止当前正在播放的音调。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Tone
**返回值：**
| 类型 | 说明 |
| :------------- | :---------------------------- |
| Promise | Promise对象。无返回结果的Promise对象。 |
**示例：**
```ts
tonePlayer.stop().then(() => {
console.info('promise call stop finish');
}).catch(() => {
console.error('promise call stop fail');
});
```
### release9+
release(callback: AsyncCallback<void>): void
释放与此TonePlayer对象关联的资源。使用callback异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Tone
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
| :------- | :------------------- | :--- | :---------------------------- |
| callback | AsyncCallback | 是 | 回调函数。当释放与此TonePlayer对象关联的资源成功，err为undefined，否则为错误对象。 |
**示例：**
```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>
释放与此TonePlayer对象关联的资源。使用Promise异步回调。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Tone
**返回值：**
| 类型 | 说明 |
| :------------- | :---------------------------- |
| Promise | Promise对象。无返回结果的Promise对象。 |
**示例：**
```ts
tonePlayer.release().then(() => {
console.info('promise call release');
}).catch(() => {
console.error('promise call release fail');
});
```
## AsrProcessingController12+
ASR处理控制器
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
### setAsrAecMode12+
setAsrAecMode(mode: AsrAecMode): boolean
设置ASR AEC模式，同步返回结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
**参数：**
| 参数名| 类型 | 必填 | 说明 |
|-------|----------------------------|-------|-------|
| mode | [AsrAecMode](#asraecmode12) | 是 |ASR AEC 模式。 |
**返回值：**
| 类型 | 说明 |
|-------|---------------------------------------|
| boolean | 返回设置ASR AEC模式结果，true为设置成功，false为设置失败。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
|---------|------------------------------------------|
| 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. |
**示例：**
```ts
let flag = asrProcessingController.setAsrAecMode(audio.AsrAecMode.BYPASS);
```
### getAsrAecMode12+
getAsrAecMode(): AsrAecMode
获取ASR AEC模式，同步返回结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
**返回值：**
| 类型 | 说明 |
|-------|-------|
| [AsrAecMode](#asraecmode12) |ASR AEC 模式 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 6800104 | Operation not allowed. |
**示例：**
```ts
let mode = asrProcessingController.getAsrAecMode();
```
### setAsrNoiseSuppressionMode12+
setAsrNoiseSuppressionMode(mode: AsrNoiseSuppressionMode): boolean
设置ASR 噪音抑制模式，同步返回结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
**参数：**
| 参数名| 类型 | 必填 | 说明 |
|-------|-------------------------------------------------------|-------|-------|
| mode | [AsrNoiseSuppressionMode](#asrnoisesuppressionmode12) | 是 |ASR 噪音抑制模式。 |
**返回值：**
| 类型 | 说明 |
|-------|----------------------------------------|
| boolean | 返回设置ASR 噪音抑制模式结果，true为设置成功，false为设置失败。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
|---------|------------------------------------------|
| 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. |
**示例：**
```ts
let flag = asrProcessingController.setAsrNoiseSuppressionMode(audio.AsrNoiseSuppressionMode.BYPASS);
```
### getAsrNoiseSuppressionMode12+
getAsrNoiseSuppressionMode(): AsrNoiseSuppressionMode
获取ASR 噪音抑制模式，同步返回结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
**返回值：**
| 类型 |说明 |
|-------------------------|-------|
| [AsrNoiseSuppressionMode](#asrnoisesuppressionmode12) |ASR 噪音抑制模式。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 6800104 | Operation not allowed. |
**示例：**
```ts
let mode = asrProcessingController.getAsrNoiseSuppressionMode();
```
### isWhispering12+
isWhispering(): boolean
查询耳语状态。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
**返回值：**
| 类型 | 说明 |
|-------|--------------------------|
| boolean | 返回耳语状态，true为开启，false为关闭。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 6800104 | Operation not allowed. |
**示例：**
```ts
let flag = asrProcessingController.isWhispering();
```
### setAsrWhisperDetectionMode12+
setAsrWhisperDetectionMode(mode: AsrWhisperDetectionMode): boolean
设置耳语检测模式。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
|------|---------------------|-------|--------|
| mode | [AsrWhisperDetectionMode](#asrwhisperdetectionmode12) | 是 | 耳语检测模式。 |
**返回值：**
| 类型 | 说明 |
|-------|----------------------------------------|
| boolean | 返回设置耳语检测模式结果，true为设置成功，false为设置失败。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
|---------|------------------------------------------|
| 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. |
**示例：**
```ts
let flag = asrProcessingController.setAsrWhisperDetectionMode(audio.AsrWhisperDetectionMode.BYPASS);
```
### getAsrWhisperDetectionMode12+
getAsrWhisperDetectionMode(): AsrWhisperDetectionMode
获取耳语检测模式，同步返回结果。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
**返回值：**
| 类型 | 说明 |
|-------|--------|
| [AsrWhisperDetectionMode](#asrwhisperdetectionmode12) | 耳语检测模式。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
|---------|------------------------------------------|
| 202 | Caller is not a system application. |
| 6800104 | Operation not allowed. |
**示例：**
```ts
let mode = asrProcessingController.getAsrWhisperDetectionMode();
```
### setAsrVoiceControlMode12+
setAsrVoiceControlMode(mode: AsrVoiceControlMode, enable: boolean): boolean
设置在系统通话中上报mode及通话录音的上行通路的ASR音频通路选择。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
|------|---------------------|-------|--------|
| mode | [AsrVoiceControlMode](#asrvoicecontrolmode12) | 是 | 音频通路模式。 |
| enable | boolean | 是 | 表示系统通话中上报mode及通话录音的上行通路的ASR音频通路选择开关状态。true表示打开，false表示关闭。 |
**返回值：**
| 类型 | 说明 |
|-------|---------------------------------------------------------------|
| boolean | 返回设置在系统通话中上报mode及通话录音的上行通路的ASR音频通路选择的结果。true为设置成功，false为设置失败。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
|---------|------------------------------------------|
| 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. |
**示例：**
```ts
let flag = asrProcessingController.setAsrVoiceControlMode(audio.AsrVoiceControlMode.AUDIO_2_VOICE_TX, true);
```
### setAsrVoiceMuteMode12+
setAsrVoiceMuteMode(mode: AsrVoiceMuteMode, enable: boolean): boolean
在系统通话中，对ASR音频通路进行静音控制。
**系统接口：** 该接口为系统接口。
**系统能力：** SystemCapability.Multimedia.Audio.Capturer
**参数：**
| 参数名 | 类型 | 必填 | 说明 |
|------|---------------------------------------|-------|----------|
| mode | [AsrVoiceMuteMode](#asrvoicemutemode12) | 是 | 静音控制模式。 |
| enable | boolean | 是 | 表示在系统通话中设置ASR音频通路静音状态。true表示静音，false表示非静音。 |
**返回值：**
| 类型 | 说明 |
|-------|--------------------------------------------------|
| boolean | 返回在系统通话中，对ASR音频通路进行静音控制的结果。true为设置成功，false为设置失败。 |
**错误码：**
以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。
| 错误码ID | 错误信息 |
|---------|------------------------------------------|
| 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. |
**示例：**
```ts
let flag = asrProcessingController.setAsrVoiceMuteMode(audio.AsrVoiceMuteMode.OUTPUT_MUTE, true);
```