1# @ohos.multimedia.audio (音频管理)(系统接口) 2<!--Kit: Audio Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @songshenke--> 5<!--Designer: @caixuejiang; @hao-liangfei; @zhanganxiang--> 6<!--Tester: @Filger--> 7<!--Adviser: @zengyawen--> 8 9音频管理提供管理音频的一些基础能力，包括对音频音量、音频设备的管理，以及对音频数据的采集和渲染等。 10 11该模块提供以下音频相关的常用功能： 12 13- [AudioManager](#audiomanager)：音频管理。 14- [TonePlayer](#toneplayer9)：用于管理和播放DTMF（Dual Tone Multi Frequency，双音多频）音调，如拨号音、通话回铃音等。 15 16> **说明：** 17> 18> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 19> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.multimedia.audio (音频管理)](arkts-apis-audio.md)。 20 21## 导入模块 22 23```ts 24import { audio } from '@kit.AudioKit'; 25``` 26 27## 常量 28 29**系统接口：** 该接口为系统接口。 30 31**系统能力：** SystemCapability.Multimedia.Audio.Device 32 33| 名称 | 类型 | 只读 | 说明 | 34| --------------------------------------- | ----------| ---- | ------------------ | 35| LOCAL_NETWORK_ID<sup>9+</sup> | string | 是 | 本地设备网络id。 | 36 37## audio.createTonePlayer<sup>9+</sup> 38 39createTonePlayer(options: AudioRendererInfo, callback: AsyncCallback<TonePlayer>): void 40 41创建DTMF播放器。使用callback异步回调。 42 43**系统接口：** 该接口为系统接口。 44 45**系统能力：** SystemCapability.Multimedia.Audio.Tone 46 47**参数：** 48 49| 参数名 | 类型 | 必填 | 说明 | 50| -------- | ----------------------------------------------- | ---- | -------------- | 51| options | [AudioRendererInfo](arkts-apis-audio-i.md#audiorendererinfo8) | 是 | 配置音频渲染器信息。| 52| callback | AsyncCallback<[TonePlayer](#toneplayer9)> | 是 | 回调函数。当获取DTMF播放器成功，err为undefined，data为获取到的DTMF播放器对象；否则为错误对象。| 53 54**示例：** 55 56```ts 57import { audio } from '@kit.AudioKit'; 58 59let audioRendererInfo: audio.AudioRendererInfo = { 60 usage : audio.StreamUsage.STREAM_USAGE_DTMF, 61 rendererFlags : 0 62}; 63let tonePlayer: audio.TonePlayer; 64 65audio.createTonePlayer(audioRendererInfo, (err, data) => { 66 console.info(`callback call createTonePlayer: audioRendererInfo: ${audioRendererInfo}`); 67 if (err) { 68 console.error(`callback call createTonePlayer return error: ${err.message}`); 69 } else { 70 console.info(`callback call createTonePlayer return data: ${data}`); 71 tonePlayer = data; 72 } 73}); 74``` 75 76## audio.createTonePlayer<sup>9+</sup> 77 78createTonePlayer(options: AudioRendererInfo): Promise<TonePlayer> 79 80创建DTMF播放器。使用Promise异步回调。 81 82**系统接口：** 该接口为系统接口。 83 84**系统能力：** SystemCapability.Multimedia.Audio.Tone 85 86**参数：** 87 88| 参数名 | 类型 | 必填 | 说明 | 89| :------ | :---------------------------------------------| :--- | :----------- | 90| options | [AudioRendererInfo](arkts-apis-audio-i.md#audiorendererinfo8) | 是 | 配置音频渲染器信息。 | 91 92**返回值：** 93 94| 类型 | 说明 | 95| ----------------------------------------- | -------------------------------- | 96| Promise<[TonePlayer](#toneplayer9)> | Promise对象，返回DTMF播放器对象。 | 97 98**示例：** 99 100```ts 101import { audio } from '@kit.AudioKit'; 102 103let tonePlayer: audio.TonePlayer; 104async function createTonePlayerBefore(){ 105 let audioRendererInfo: audio.AudioRendererInfo = { 106 usage : audio.StreamUsage.STREAM_USAGE_DTMF, 107 rendererFlags : 0 108 }; 109 tonePlayer = await audio.createTonePlayer(audioRendererInfo); 110} 111``` 112 113## audio.createAsrProcessingController<sup>12+</sup> 114 115createAsrProcessingController(audioCapturer: AudioCapturer): AsrProcessingController 116 117获取ASR处理控制器 118 119**系统接口：** 该接口为系统接口。 120 121**系统能力：** SystemCapability.Multimedia.Audio.Capturer 122 123**参数：** 124 125| 参数名 | 类型 | 必填 | 说明 | 126| :------ | :---------------------------------------------| :--- |:---------| 127| audioCapturer | [AudioCapturer](arkts-apis-audio-AudioCapturer.md) | 是 | 音频采集器对象。 | 128 129**返回值：** 130 131| 类型 | 说明 | 132|-------------------------------------------------------| ------------ | 133| [AsrProcessingController](#asrprocessingcontroller12) | ASR处理控制器对象。 | 134 135**错误码：** 136 137以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 138 139| 错误码ID | 错误信息 | 140|---------|------------------------------------------| 141| 202 | Caller is not a system application. | 142| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 143| 6800101 | Parameter verification failed. | 144| 6800104 | Operation not allowed. | 145 146**示例：** 147 148```ts 149import { audio } from '@kit.AudioKit'; 150 151let audioStreamInfo: audio.AudioStreamInfo = { 152 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, 153 channels: audio.AudioChannel.CHANNEL_2, 154 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 155 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 156}; 157 158let audioCapturerInfo: audio.AudioCapturerInfo = { 159 source: audio.SourceType.SOURCE_TYPE_MIC, 160 capturerFlags: 0 161}; 162 163let audioCapturerOptions: audio.AudioCapturerOptions = { 164 streamInfo: audioStreamInfo, 165 capturerInfo: audioCapturerInfo 166}; 167 168audio.createAudioCapturer(audioCapturerOptions, (err, data) => { 169 if (err) { 170 console.error(`AudioCapturer Created : Error: ${err}`); 171 } else { 172 console.info('AudioCapturer Created : Success : SUCCESS'); 173 let audioCapturer = data; 174 let asrProcessingController = audio.createAsrProcessingController(audioCapturer); 175 console.info('AsrProcessingController Created : Success : SUCCESS'); 176 } 177}); 178``` 179 180## AudioVolumeType 181 182枚举，音频流类型。 183 184**系统接口：** 该接口为系统接口。 185 186**系统能力：** SystemCapability.Multimedia.Audio.Volume 187 188| 名称 | 值 | 说明 | 189| ---------------------------- | ------ | ---------- | 190| SYSTEM<sup>20+</sup> | 6 | 系统音。| 191| ULTRASONIC<sup>10+</sup> | 10 | 超声波。| 192| ALL<sup>9+</sup> | 100 | 所有公共音频流。| 193 194## InterruptRequestResultType<sup>9+</sup> 195 196枚举，音频中断请求结果类型。 197 198**系统接口：** 该接口为系统接口。 199 200**系统能力：** SystemCapability.Multimedia.Audio.Interrupt 201 202| 名称 | 值 | 说明 | 203| ---------------------------- | ------ | ---------- | 204| INTERRUPT_REQUEST_GRANT | 0 | 请求音频中断成功。 | 205| INTERRUPT_REQUEST_REJECT | 1 | 请求音频中断失败，可能具有较高优先级类型。 | 206 207## DeviceFlag 208 209枚举，可获取的设备种类。 210 211**系统接口：** 该接口为系统接口。 212 213**系统能力：** SystemCapability.Multimedia.Audio.Device 214 215| 名称 | 值 | 说明 | 216| ------------------------------- | ------ |---------------------------| 217| NONE_DEVICES_FLAG<sup>9+</sup> | 0 | 无设备。 | 218| DISTRIBUTED_OUTPUT_DEVICES_FLAG<sup>9+</sup> | 4 | 分布式输出设备。 | 219| DISTRIBUTED_INPUT_DEVICES_FLAG<sup>9+</sup> | 8 | 分布式输入设备。 | 220| ALL_DISTRIBUTED_DEVICES_FLAG<sup>9+</sup> | 12 | 分布式输入和输出设备。 | 221 222## EffectFlag<sup>18+</sup> 223 224枚举，音效分类。 225 226**系统接口：** 该接口为系统接口。 227 228**系统能力：** SystemCapability.Multimedia.Audio.Core 229 230| 名称 | 值 | 说明 | 231| ------------------------------- | ------ |------------------------------| 232| RENDER_EFFECT_FLAG | 0 | 下行音效类型。 | 233| CAPTURE_EFFECT_FLAG | 1 | 上行音效类型。 | 234 235## AudioEffectProperty<sup>18+</sup> 236 237音效属性。 238 239**系统接口：** 该接口为系统接口。 240 241**系统能力：** SystemCapability.Multimedia.Audio.Core 242 243| 名称 | 类型 | 只读 | 可选 | 说明 | 244| ------------------ | ---- | ---- |---| --------- | 245| name | string | 否 | 否 | 音效名称。 | 246| category | string | 否 | 否 | 音效分类。 | 247| flag | [EffectFlag](#effectflag18) | 否 | 否 | 音效分类。 | 248 249## StreamUsage 250 251枚举，音频流使用类型。 252 253**系统接口：** 该接口为系统接口。 254 255**系统能力：** SystemCapability.Multimedia.Audio.Core 256 257| 名称 | 值 | 说明 | 258| ------------------------------------------| ------ |-----------------------------| 259| STREAM_USAGE_SYSTEM<sup>10+</sup> | 9 | 系统音(如屏幕锁定或按键音)。 | 260| STREAM_USAGE_DTMF<sup>10+</sup> | 14 | 拨号音。 | 261| STREAM_USAGE_ENFORCED_TONE<sup>10+</sup> | 15 | 强制音(如相机快门音)。 | 262| STREAM_USAGE_ULTRASONIC<sup>10+</sup> | 16 | 超声波（目前仅提供给MSDP使用）。 | 263| STREAM_USAGE_VOICE_CALL_ASSISTANT<sup>12+</sup> | 21 | 通话辅助语音。 | 264 265## InterruptRequestType<sup>9+</sup> 266 267枚举，音频中断请求类型。 268 269**系统接口：** 该接口为系统接口。 270 271**系统能力：** SystemCapability.Multimedia.Audio.Interrupt 272 273| 名称 | 值 | 说明 | 274| ---------------------------------- | ------ | ------------------------- | 275| INTERRUPT_REQUEST_TYPE_DEFAULT | 0 | 默认类型，可中断音频请求。 | 276 277## VolumeFlag<sup>12+</sup> 278 279枚举，音量相关操作。 280 281**系统接口：** 该接口为系统接口。 282 283**系统能力：** SystemCapability.Multimedia.Audio.Volume 284 285| 名称 | 值 | 说明 | 286| ---------------------------------- |---|----------| 287| FLAG_SHOW_SYSTEM_UI | 1 | 拉起系统音量条。 | 288 289## AsrNoiseSuppressionMode<sup>12+</sup> 290 291枚举，ASR 噪音抑制模式 292 293**系统接口：** 该接口为系统接口。 294 295**系统能力：** SystemCapability.Multimedia.Audio.Capturer 296 297| 名称| 值 | 说明 | 298|-------|-------|-------| 299| BYPASS | 0 |旁路噪音抑制。| 300| STANDARD | 1 |标准噪音抑制。| 301| NEAR_FIELD | 2 |近场噪音抑制。| 302| FAR_FIELD | 3 |远场噪音抑制。| 303 304## AsrAecMode<sup>12+</sup> 305 306枚举，ASR AEC 模式 307 308**系统接口：** 该接口为系统接口。 309 310**系统能力：** SystemCapability.Multimedia.Audio.Capturer 311 312| 名称| 值 | 说明 | 313|-------|-------|-------| 314| BYPASS | 0 |BYPASS AEC| 315| STANDARD | 1 |STANDARD AEC| 316 317## AsrWhisperDetectionMode<sup>12+</sup> 318 319枚举，ASR（Automatic Speech Recognition，自动语音识别）耳语检测模式。 320 321**系统接口：** 该接口为系统接口。 322 323**系统能力：** SystemCapability.Multimedia.Audio.Capturer 324 325| 名称 | 值 | 说明 | 326|-----|---|----------| 327| BYPASS | 0 | 不启用检测模型。 | 328| STANDARD | 1 | 耳语检测模型。 | 329 330## AsrVoiceControlMode<sup>12+</sup> 331 332枚举，ASR音频通路模式。 333 334**系统接口：** 该接口为系统接口。 335 336**系统能力：** SystemCapability.Multimedia.Audio.Capturer 337 338| 名称 | 值 | 说明 | 339|-------------------------|---|---------------------------------------| 340| AUDIO_2_VOICE_TX | 0 | 仅媒体音频流生效。 | 341| AUDIO_MIX_2_VOICE_TX | 1 | 媒体音频流和MIC音频流均生效。 | 342| AUDIO_2_VOICE_TX_EX | 2 | 仅媒体音频流生效，将媒体流上报给通话录音。 | 343| AUDIO_MIX_2_VOICE_TX_EX | 3 | 媒体音频流和MIC音频流均生效，将媒体流上报给通话录音。 | 344 345## AsrVoiceMuteMode<sup>12+</sup> 346 347枚举，ASR静音模式。 348 349**系统接口：** 该接口为系统接口。 350 351**系统能力：** SystemCapability.Multimedia.Audio.Capturer 352 353| 名称 | 值 | 说明 | 354|----------------|---|---------------------| 355| OUTPUT_MUTE | 0 | 本地输出静音。 | 356| INPUT_MUTE | 1 | 本地的MIC输入静音。 | 357| TTS_MUTE | 2 | 应用下发的媒体音频本地静音。 | 358| CALL_MUTE | 3 | 通话语音流静音。 | 359| OUTPUT_MUTE_EX | 4 | 本地输出静音，媒体音频流送给通话录音。 | 360 361## InterruptResult<sup>9+</sup> 362 363音频中断结果。 364 365**系统接口：** 该接口为系统接口。 366 367**系统能力：** SystemCapability.Multimedia.Audio.Interrupt 368 369| 名称 | 类型 | 只读 | 可选 | 说明 | 370| --------------| -------------------------------------------------------------- | ---- |---| ---------------- | 371| requestResult | [InterruptRequestResultType](#interruptrequestresulttype9) | 否 | 否 | 表示音频请求中断类型。 | 372| interruptNode | number | 否 | 否 | 音频请求中断的节点。 | 373 374## VolumeEvent<sup>9+</sup> 375 376音量改变时，应用接收的事件。 377 378**系统接口：** 该接口为系统接口。 379 380**系统能力：** SystemCapability.Multimedia.Audio.Volume 381 382| 名称 | 类型 | 只读 | 可选 | 说明 | 383| ---------- | ----------------------------------- | ---- |---|-------------------------------------------| 384| volumeGroupId | number | 否 | 否 | 音量组id，可用于getGroupManager入参。 | 385| networkId | string | 否 | 否 | 网络id。 | 386 387## ConnectType<sup>9+</sup> 388 389枚举，设备连接类型。 390 391**系统接口：** 该接口为系统接口。 392 393**系统能力：** SystemCapability.Multimedia.Audio.Volume 394 395| 名称 | 值 | 说明 | 396| :------------------------------ | :----- | :--------------------- | 397| CONNECT_TYPE_LOCAL | 1 | 本地设备。 | 398| CONNECT_TYPE_DISTRIBUTED | 2 | 分布式设备。 | 399 400## VolumeGroupInfos<sup>9+</sup> 401 402音量组信息，数组类型，为[VolumeGroupInfo](#volumegroupinfo9)的数组，只读。 403 404**系统接口：** 该接口为系统接口。 405 406**系统能力：** SystemCapability.Multimedia.Audio.Volume 407 408## VolumeGroupInfo<sup>9+</sup> 409 410音量组信息。 411 412**系统接口：** 该接口为系统接口。 413 414**系统能力：** SystemCapability.Multimedia.Audio.Volume 415 416| 名称 | 类型 | 只读 | 可选 | 说明 | 417| -------------------------- | -------------------------- | ---- | ---- | ---------- | 418| networkId<sup>9+</sup> | string | 是 | 否 | 组网络id。 | 419| groupId<sup>9+</sup> | number | 是 | 否 | 组设备组id。 | 420| mappingId<sup>9+</sup> | number | 是 | 否 | 组映射id。 | 421| groupName<sup>9+</sup> | string | 是 | 否 | 组名。 | 422| type<sup>9+</sup> | [ConnectType](#connecttype9)| 是 | 否 | 连接设备类型。 | 423 424## SourceType<sup>8+</sup> 425 426枚举，音源类型。 427 428**系统接口：** 该接口为系统接口。 429 430**系统能力：** SystemCapability.Multimedia.Audio.Core 431 432| 名称 | 值 | 说明 | 433| :------------------------------------------- | :----- | :--------------------- | 434| SOURCE_TYPE_WAKEUP <sup>10+</sup> | 3 | 语音唤醒音频流录制音频源。<br/>**需要权限：** ohos.permission.MANAGE_INTELLIGENT_VOICE | 435| SOURCE_TYPE_VOICE_CALL<sup>11+</sup> | 4 | 通话录音的音频源。<br/>**需要权限：** ohos.permission.RECORD_VOICE_CALL | 436| SOURCE_TYPE_VOICE_TRANSCRIPTION<sup>18+</sup> | 12 | 语音转写音频源。 | 437 438## VolumeAdjustType<sup>10+</sup> 439 440枚举，音量调节类型。 441 442**系统接口：** 该接口为系统接口。 443 444**系统能力：** SystemCapability.Multimedia.Audio.Volume 445 446| 名称 | 值 | 说明 | 447| :--------------------- | :----- | :-------------------------------------------- | 448| VOLUME_UP | 0 | 向上调节音量。 | 449| VOLUME_DOWN | 1 | 向下调节音量。 | 450 451## AudioManager 452 453管理音频音量和音频设备。在调用AudioManager的接口前，需要先通过[getAudioManager](arkts-apis-audio-f.md#audiogetaudiomanager)创建实例。 454 455### setExtraParameters<sup>11+</sup> 456 457setExtraParameters(mainKey: string, kvpairs: Record<string, string\>): Promise<void> 458 459音频扩展参数设置。使用Promise异步回调。 460 461**需要权限：** ohos.permission.MODIFY_AUDIO_SETTINGS 462 463**系统接口：** 该接口为系统接口。 464 465**系统能力：** SystemCapability.Multimedia.Audio.Core 466 467**参数：** 468 469| 参数名 | 类型 | 必填 | 说明 | 470| ------ | ------ | ---- | ---------------------- | 471| mainKey | string | 是 | 被设置的音频参数的主键。 | 472| kvpairs | Record<string, string\> | 是 | 被设置的音频参数的子键值对。 | 473 474**返回值：** 475 476| 类型 | 说明 | 477| ------------------- | ------------------------------- | 478| Promise<void> | Promise对象。无返回结果的Promise对象。 | 479 480**错误码：** 481 482以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 483 484| 错误码ID | 错误信息 | 485|-----|------------------------------------------------------------------------------------------------------------| 486| 201 | Permission denied. | 487| 202 | Not system App. | 488| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 489| 6800101 | Parameter verification failed. | 490 491**示例：** 492 493```ts 494import { BusinessError } from '@kit.BasicServicesKit'; 495 496let kvpairs = {} as Record<string, string>; 497kvpairs = { 498 'key_example': 'value_example' 499}; 500 501audioManager.setExtraParameters('key_example', kvpairs).then(() => { 502 console.info('Promise returned to indicate a successful setting of the extra parameters.'); 503}).catch((err: BusinessError) => { 504 console.error(`Failed to set the audio extra parameters ${err}`); 505}); 506``` 507 508### getExtraParameters<sup>11+</sup> 509 510getExtraParameters(mainKey: string, subKeys?: Array\<string>): Promise\<Record\<string, string>> 511 512获取指定音频参数值。使用Promise异步回调。 513 514**系统接口：** 该接口为系统接口。 515 516**系统能力：** SystemCapability.Multimedia.Audio.Core 517 518**参数：** 519 520| 参数名 | 类型 | 必填 | 说明 | 521| ------ | ------ |--| ---------------------- | 522| mainKey | string | 是 | 待获取的音频参数的主键。 | 523| subKeys | Array\<string> | 否 | 待获取的音频参数的子键。 | 524 525**返回值：** 526 527| 类型 | 说明 | 528| --------------------- | ----------------------------------- | 529| Promise\<Record\<string, string>> | Promise对象，返回获取的音频参数的值。 | 530 531**错误码：** 532 533以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 534 535| 错误码ID | 错误信息 | 536| ------ | -------------------------| 537| 202 | Not system App. | 538| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 539| 6800101 | Parameter verification failed. | 540 541**示例：** 542 543```ts 544import { BusinessError } from '@kit.BasicServicesKit'; 545 546let subKeys: Array<String> = ['key_example']; 547audioManager.getExtraParameters('key_example', subKeys).then((value: Record<string, string>) => { 548 console.info(`Promise returned to indicate that the value of the audio extra parameters is obtained ${value}.`); 549}).catch((err: BusinessError) => { 550 console.error(`Failed to get the audio extra parameters ${err}`); 551}); 552``` 553 554### setAudioScene<sup>8+</sup> 555 556setAudioScene\(scene: AudioScene, callback: AsyncCallback<void\>\): void 557 558设置音频场景模式。使用callback异步回调。 559 560**系统接口：** 该接口为系统接口。 561 562**系统能力：** SystemCapability.Multimedia.Audio.Communication 563 564**参数：** 565 566| 参数名 | 类型 | 必填 | 说明 | 567| :------- | :----------------------------------- | :--- | :------------------- | 568| scene | [AudioScene](arkts-apis-audio-e.md#audioscene8) | 是 | 音频场景模式。 | 569| callback | AsyncCallback<void\> | 是 | 回调函数。当设置音频场景模式成功，err为undefined，否则为错误对象。 | 570 571**示例：** 572 573```ts 574import { BusinessError } from '@kit.BasicServicesKit'; 575 576audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL, (err: BusinessError) => { 577 if (err) { 578 console.error(`Failed to set the audio scene mode. ${err}`); 579 return; 580 } 581 console.info('Callback invoked to indicate a successful setting of the audio scene mode.'); 582}); 583``` 584 585### setAudioScene<sup>8+</sup> 586 587setAudioScene\(scene: AudioScene\): Promise<void\> 588 589设置音频场景模式。使用Promise异步回调。 590 591**系统接口：** 该接口为系统接口。 592 593**系统能力：** SystemCapability.Multimedia.Audio.Communication 594 595**参数：** 596 597| 参数名 | 类型 | 必填 | 说明 | 598| :----- | :----------------------------------- | :--- | :------------- | 599| scene | [AudioScene](arkts-apis-audio-e.md#audioscene8) | 是 | 音频场景模式。 | 600 601**返回值：** 602 603| 类型 | 说明 | 604| :------------- | :------------------- | 605| Promise<void\> | Promise对象。无返回结果的Promise对象。 | 606 607**示例：** 608 609```ts 610import { BusinessError } from '@kit.BasicServicesKit'; 611 612audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL).then(() => { 613 console.info('Promise returned to indicate a successful setting of the audio scene mode.'); 614}).catch((err: BusinessError) => { 615 console.error(`Failed to set the audio scene mode ${err}`); 616}); 617``` 618 619### getEffectManager<sup>18+</sup> 620 621getEffectManager(): AudioEffectManager 622 623获取音效会话管理器。 624 625**系统接口：** 该接口为系统接口。 626 627**系统能力：** SystemCapability.Multimedia.Audio.Core 628 629**返回值：** 630 631| 类型 | 说明 | 632|----------------------------------------------| ----------------------------- | 633| [AudioEffectManager](#audioeffectmanager18) | AudioEffectManager实例。 | 634 635**错误码：** 636 637以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 638 639| 错误码ID | 错误信息 | 640| ------- | --------------------------------------------| 641| 202 | Not system App. | 642 643**示例：** 644 645```ts 646import { audio } from '@kit.AudioKit'; 647 648let audioEffectManager: audio.AudioEffectManager = audioManager.getEffectManager(); 649``` 650 651### disableSafeMediaVolume<sup>12+</sup> 652 653disableSafeMediaVolume(): Promise<void> 654 655设置安全音量为非激活状态。使用Promise异步回调。 656 657设置为非激活状态后，当设备长时间高音量播放时，不再自动提醒用户降低到安全音量。 658 659**需要权限：** ohos.permission.MODIFY_AUDIO_SETTINGS 660 661**系统接口：** 该接口为系统接口。 662 663**系统能力：** SystemCapability.Multimedia.Audio.Core 664 665**返回值：** 666 667| 类型 | 说明 | 668|------------------------------------------| ----------------------------- | 669| Promise<void> | Promise对象。无返回结果的Promise对象。 | 670 671**错误码：** 672 673以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 674 675| 错误码ID | 错误信息 | 676| ------- | --------------------------------------------| 677| 201 | Permission denied. | 678| 202 | Not system App. | 679 680**示例：** 681 682```ts 683import { BusinessError } from '@kit.BasicServicesKit'; 684 685audioManager.disableSafeMediaVolume().then(() => { 686 console.info('disableSafeMediaVolume success.'); 687}).catch((err: BusinessError) => { 688 console.error(`disableSafeMediaVolume fail: ${err.code},${err.message}`); 689}); 690``` 691 692### on('volumeChange')<sup>(deprecated)</sup> 693 694on(type: 'volumeChange', callback: Callback\<VolumeEvent>): void 695 696> **说明：** 697> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用AudioVolumeManager中的[on('volumeChange')](arkts-apis-audio-AudioVolumeManager.md#onvolumechangedeprecated)替代。 698 699监听系统音量变化事件（当系统音量发生变化时触发）。使用callback异步回调。 700 701目前此订阅接口在单进程多AudioManager实例的使用场景下，仅最后一个实例的订阅生效，其他实例的订阅会被覆盖（即使最后一个实例没有进行订阅），因此推荐使用单一AudioManager实例进行开发。 702 703**系统接口：** 该接口为系统接口。 704 705**系统能力：** SystemCapability.Multimedia.Audio.Volume 706 707**参数：** 708 709| 参数名 | 类型 | 必填 | 说明 | 710| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 711| type | string | 是 | 事件回调类型，支持的事件为'volumeChange'，当系统音量发生变化时，触发该事件。 | 712| callback | Callback<[VolumeEvent](#volumeevent9)> | 是 | 回调函数，返回变化后的音量信息。 | 713 714**示例：** 715 716```ts 717audioManager.on('volumeChange', (volumeEvent: audio.VolumeEvent) => { 718 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 719 console.info(`Volume level: ${volumeEvent.volume} `); 720 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 721}); 722``` 723 724### on('ringerModeChange')<sup>(deprecated)</sup> 725 726on(type: 'ringerModeChange', callback: Callback\<AudioRingMode>): void 727 728监听铃声模式变化事件（当[铃声模式](arkts-apis-audio-e.md#audioringmode)发生改变时触发）。使用callback异步回调。 729 730> **说明：** 731> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用AudioVolumeGroupManager中的[on('ringerModeChange')](arkts-apis-audio-AudioVolumeGroupManager.md#onringermodechange9)替代。 732 733**系统接口：** 该接口为系统接口。 734 735**系统能力：** SystemCapability.Multimedia.Audio.Communication 736 737**参数：** 738 739| 参数名 | 类型 | 必填 | 说明 | 740| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 741| type | string | 是 | 事件回调类型，支持的事件为'ringerModeChange'，当铃声模式发生改变时，触发该事件。 | 742| callback | Callback<[AudioRingMode](arkts-apis-audio-e.md#audioringmode)> | 是 | 回调函数，返回变化后的铃音模式。 | 743 744**示例：** 745 746```ts 747audioManager.on('ringerModeChange', (ringerMode: audio.AudioRingMode) => { 748 console.info(`Updated ringermode: ${ringerMode}`); 749}); 750``` 751 752## forceVolumeKeyControlType<sup>20+</sup> 753 754forceVolumeKeyControlType(volumeType: AudioVolumeType, duration: number): void 755 756设置音量键调节类型。 757 758**需要权限：** ohos.permission.MODIFY_AUDIO_SETTINGS 759 760**系统接口：** 此接口为系统接口。 761 762**系统能力：** SystemCapability.Multimedia.Audio.Volume 763 764**参数：** 765 766| 参数名 | 类型 | 必填 | 说明 | 767| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 768| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 应用程序期望控制的音量类型。 | 769| duration |number | 是 | 无音量键事件时，控制音量类型的持续时间。当计时器到期时，强制音量类型设置将被取消，最大持续时间不得超过10秒。如果持续时间设置为-1，则取消该设置。 | 770 771**错误码：** 772以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 773 774| 错误码ID | 错误信息 | 775| ------- | --------------------------------------------| 776| 201 | Permission denied. | 777| 202 | Not system App. | 778| 6800101 | Parameter verification failed. | 779| 6800301 | Crash or blocking occurs in system process. | 780 781**示例：** 782 783```ts 784import { audio } from '@kit.AudioKit'; 785 786let audioManager = audio.getAudioManager(); 787let audioVolumeManager = audioManager.getVolumeManager(); 788 789// 设置音量保持类型为响铃模式。 790let volumeType = audio.AudioVolumeType.RINGTONE; 791let duration = 10; 792audioVolumeManager.forceVolumeKeyControlType(volumeType, duration); 793 794// 取消音量保持类型，恢复默认音量控制。 795let volumeTypeDefault = audio.AudioVolumeType.MEDIA; 796let durationToCancel = -1; 797audioVolumeManager.forceVolumeKeyControlType(volumeTypeDefault, durationToCancel); 798``` 799 800## AudioVolumeManager<sup>9+</sup> 801 802音量管理。在使用AudioVolumeManager的接口前，需要使用[getVolumeManager](arkts-apis-audio-AudioManager.md#getvolumemanager9)获取AudioVolumeManager实例。 803 804### getVolumeGroupInfos<sup>9+</sup> 805 806getVolumeGroupInfos(networkId: string, callback: AsyncCallback<VolumeGroupInfos\>\): void 807 808获取音量组信息列表。使用callback异步回调。 809 810**系统接口：** 该接口为系统接口。 811 812**系统能力：** SystemCapability.Multimedia.Audio.Volume 813 814**参数：** 815 816| 参数名 | 类型 | 必填 | 说明 | 817| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 818| networkId | string | 是 | 设备的网络id。本地设备audio.LOCAL_NETWORK_ID。 | 819| callback | AsyncCallback<[VolumeGroupInfos](#volumegroupinfos9)> | 是 | 回调函数。当获取音量组信息列表成功，err为undefined，data为获取到的音量组信息列表；否则为错误对象。 | 820 821**示例：** 822```ts 823import { BusinessError } from '@kit.BasicServicesKit'; 824 825audioVolumeManager.getVolumeGroupInfos(audio.LOCAL_NETWORK_ID, (err: BusinessError, value: audio.VolumeGroupInfos) => { 826 if (err) { 827 console.error(`Failed to obtain the volume group infos list. ${err}`); 828 return; 829 } 830 console.info('Callback invoked to indicate that the volume group infos list is obtained.'); 831}); 832``` 833 834### getVolumeGroupInfos<sup>9+</sup> 835 836getVolumeGroupInfos(networkId: string\): Promise<VolumeGroupInfos\> 837 838获取音量组信息列表。使用Promise异步回调。 839 840**系统接口：** 该接口为系统接口。 841 842**系统能力：** SystemCapability.Multimedia.Audio.Volume 843 844**参数：** 845 846| 参数名 | 类型 | 必填 | 说明 | 847| ---------- | ------------------| ---- | -------------------- | 848| networkId | string | 是 | 设备的网络id。本地设备audio.LOCAL_NETWORK_ID。 | 849 850**返回值：** 851 852| 类型 | 说明 | 853| ------------------- | ----------------------------- | 854| Promise<[VolumeGroupInfos](#volumegroupinfos9)> | Promise对象，返回音量组信息列表。 | 855 856**示例：** 857 858```ts 859async function getVolumeGroupInfos(){ 860 let volumegroupinfos: audio.VolumeGroupInfos = await audio.getAudioManager().getVolumeManager().getVolumeGroupInfos(audio.LOCAL_NETWORK_ID); 861 console.info('Promise returned to indicate that the volumeGroup list is obtained.'+JSON.stringify(volumegroupinfos)) 862} 863``` 864 865### getVolumeGroupInfosSync<sup>10+</sup> 866 867getVolumeGroupInfosSync(networkId: string\): VolumeGroupInfos 868 869获取音量组信息列表，同步返回结果。 870 871**系统接口：** 该接口为系统接口。 872 873**系统能力：** SystemCapability.Multimedia.Audio.Volume 874 875**参数：** 876 877| 参数名 | 类型 | 必填 | 说明 | 878| ---------- | ------------------| ---- | -------------------- | 879| networkId | string | 是 | 设备的网络id。本地设备audio.LOCAL_NETWORK_ID。 | 880 881**返回值：** 882 883| 类型 | 说明 | 884| ------------------- | ----------------------------- | 885| [VolumeGroupInfos](#volumegroupinfos9) | 音量组信息列表。 | 886 887**错误码：** 888 889以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 890 891| 错误码ID | 错误信息 | 892| ------- | --------------------------------------------| 893| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 894| 6800101 | Parameter verification failed. | 895 896**示例：** 897 898```ts 899import { BusinessError } from '@kit.BasicServicesKit'; 900 901try { 902 let volumegroupinfos: audio.VolumeGroupInfos = audioVolumeManager.getVolumeGroupInfosSync(audio.LOCAL_NETWORK_ID); 903 console.info(`Indicate that the volumeGroup list is obtained. ${JSON.stringify(volumegroupinfos)}`); 904} catch (err) { 905 let error = err as BusinessError; 906 console.error(`Failed to obtain the volumeGroup list ${error}`); 907} 908``` 909 910### getAppVolumePercentageForUid<sup>19+</sup> 911 912getAppVolumePercentageForUid(uid: number\): Promise<number\> 913 914根据应用ID获取指定应用的音量（范围为0到100）。使用Promise异步回调。 915 916**系统接口：** 该接口为系统接口。 917 918**系统能力：** SystemCapability.Multimedia.Audio.Volume 919 920**参数：** 921 922| 参数名 | 类型 | 必填 | 说明 | 923| ---------- | ---------------------------------------- | ---- |----------------------------------| 924| uid | number | 是 | 表示应用ID。 | 925 926**返回值：** 927 928| 类型 | 说明 | 929| ------------------- | ----------------------------- | 930| Promise<number> | Promise对象，返回应用的音量（范围为0到100）。 | 931 932**错误码：** 933 934以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 935 936| 错误码ID | 错误信息 | 937| ------- | --------------------------------------------| 938| 201 | Permission denied. | 939| 202 | Not system App. | 940| 6800101 | Parameter verification failed.| 941 942**示例：** 943 944```ts 945let uid: number = 20010041; // 应用ID。 946 947audioVolumeManager.getAppVolumePercentageForUid(20010041).then((value: number) => { 948 console.info(`app volume is ${value}.`); 949}); 950``` 951 952### setAppVolumePercentageForUid<sup>19+</sup> 953 954setAppVolumePercentageForUid(uid: number, volume: number\): Promise<void\> 955 956根据应用ID设置指定应用的音量（范围为0到100）。使用Promise异步回调。 957 958**系统接口：** 该接口为系统接口。 959 960**系统能力：** SystemCapability.Multimedia.Audio.Volume 961 962**参数：** 963 964| 参数名 | 类型 | 必填 | 说明 | 965| ---------- | ---------------------------------------- | ---- |----------| 966| uid | number | 是 | 表示应用ID。 | 967| volume | number | 是 | 要设置的音量值。 | 968 969**返回值：** 970 971| 类型 | 说明 | 972| ------------------- | ------------------------------- | 973| Promise<void> | Promise对象。无返回结果的Promise对象。 | 974 975**错误码：** 976 977以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 978 979| 错误码ID | 错误信息 | 980| ------- | --------------------------------------------| 981| 201 | Permission denied. | 982| 202 | Not system App. | 983| 6800101 | Parameter verification failed.| 984| 6800301 | Crash or blocking occurs in system process. | 985 986**示例：** 987 988```ts 989let uid: number = 20010041; // 应用ID。 990let volume: number = 20; // 要设置的音量值。 991 992audioVolumeManager.setAppVolumePercentageForUid(uid, volume).then(() => { 993 console.info(`set app volume success.`); 994}); 995``` 996 997### isAppVolumeMutedForUid<sup>19+</sup> 998 999isAppVolumeMutedForUid(uid: number, owned: boolean\): Promise<boolean\> 1000 1001根据应用ID查询应用音量是否已静音。使用Promise异步回调。 1002 1003> **说明：** 1004> 1005> 如果有多个调用者设置了静音状态，那么只有当所有调用者都取消静音状态后，此应用才会真正取消静音。 1006 1007**系统接口：** 该接口为系统接口。 1008 1009**系统能力：** SystemCapability.Multimedia.Audio.Volume 1010 1011**参数：** 1012 1013| 参数名 | 类型 | 必填 | 说明 | 1014| ---------- | ---------------------------------------- | ---- |-------------------------------------------| 1015| uid | number | 是 | 表示应用ID。 | 1016| owned | boolean | 是 | 要查询的静音状态。true查询当前调用者的静音状态，false查询应用的静音状态。 | 1017 1018**返回值：** 1019 1020| 类型 | 说明 | 1021| ------------------- |---------------------| 1022| Promise<boolean> | Promise对象。返回true表示应用为静音状态；返回false表示应用为非静音状态。 | 1023 1024**错误码：** 1025 1026以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1027 1028| 错误码ID | 错误信息 | 1029| ------- | --------------------------------------------| 1030| 201 | Permission denied. | 1031| 202 | Not system App. | 1032| 6800101 | Parameter verification failed.| 1033 1034**示例：** 1035 1036```ts 1037let uid: number = 20010041; // 应用ID。 1038 1039audioVolumeManager.isAppVolumeMutedForUid(uid, true).then((value: boolean) => { 1040 console.info(`app muted state is ${value}.`); 1041}); 1042``` 1043 1044### setAppVolumeMutedForUid<sup>19+</sup> 1045 1046setAppVolumeMutedForUid(uid: number, muted: boolean\): Promise<void\> 1047 1048根据应用ID设置应用静音状态。使用Promise异步回调。 1049 1050**系统接口：** 该接口为系统接口。 1051 1052**系统能力：** SystemCapability.Multimedia.Audio.Volume 1053 1054**参数：** 1055 1056| 参数名 | 类型 | 必填 | 说明 | 1057| ---------- | ---------------------------------------- | ---- |--------------------------------| 1058| uid | number | 是 | 表示应用ID。 | 1059| owned | boolean | 是 | 设置应用的静音状态。true设置为静音，false解除静音。 | 1060 1061**返回值：** 1062 1063| 类型 | 说明 | 1064| ------------------- | ------------------------------- | 1065| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1066 1067**错误码：** 1068 1069以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1070 1071| 错误码ID | 错误信息 | 1072| ------- | --------------------------------------------| 1073| 201 | Permission denied. | 1074| 202 | Not system App. | 1075| 6800101 | Parameter verification failed.| 1076| 6800301 | Crash or blocking occurs in system process. | 1077 1078**示例：** 1079 1080```ts 1081let uid: number = 20010041; // 应用ID。 1082 1083audioVolumeManager.setAppVolumeMutedForUid(uid, true).then(() => { 1084 console.info(`set app mute state success.`); 1085}); 1086``` 1087 1088### on('appVolumeChangeForUid')<sup>19+</sup> 1089 1090on(type: 'appVolumeChangeForUid', uid: number, callback: Callback\<VolumeEvent>): void 1091 1092监听指定应用应用级音量变化事件（当应用级音量发生变化时触发）。使用callback异步回调。 1093 1094**系统接口：** 该接口为系统接口。 1095 1096**系统能力：** SystemCapability.Multimedia.Audio.Volume 1097 1098**参数：** 1099 1100| 参数名 | 类型 | 必填 | 说明 | 1101| -------- | -------------------------------------- | ---- |-----------------------------------| 1102| type | string | 是 | 事件回调类型，支持的事件为'appVolumeChangeForUid'，当应用级音量发生变化时，触发该事件。 | 1103| uid | number | 是 | 表示应用ID。 | 1104| callback | Callback<[VolumeEvent](arkts-apis-audio-i.md#volumeevent9)> | 是 | 回调函数，返回变化后的音量信息。 | 1105 1106**错误码：** 1107 1108以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1109 1110| 错误码ID | 错误信息 | 1111| ------- | --------------------------------------------| 1112| 201 | Permission denied. | 1113| 202 | Not system App. | 1114| 6800101 | Parameter verification failed. | 1115 1116**示例：** 1117 1118```ts 1119let uid: number = 20010041; // 应用ID。 1120 1121audioVolumeManager.on('appVolumeChangeForUid', uid, (volumeEvent: audio.VolumeEvent) => { 1122 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 1123 console.info(`Volume level: ${volumeEvent.volume} `); 1124 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 1125}); 1126``` 1127 1128### off('appVolumeChangeForUid')<sup>19+</sup> 1129 1130off(type: 'appVolumeChangeForUid', callback?: Callback\<VolumeEvent>): void 1131 1132取消监听指定应用应用级音量变化事件。使用callback异步回调。 1133 1134**系统接口：** 该接口为系统接口。 1135 1136**系统能力：** SystemCapability.Multimedia.Audio.Volume 1137 1138**参数：** 1139 1140| 参数名 | 类型 | 必填 | 说明 | 1141| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 1142| type | string | 是 | 事件回调类型，支持的事件为'appVolumeChangeForUid'，当取消监听指定应用应用级音量变化事件时，触发该事件。 | 1143| callback | Callback<[VolumeEvent](arkts-apis-audio-i.md#volumeevent9)> | 否 | 回调函数，返回变化后的音量信息。 | 1144 1145**错误码：** 1146 1147以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1148 1149| 错误码ID | 错误信息 | 1150| ------- | --------------------------------------------| 1151| 201 | Permission denied. | 1152| 202 | Not system App. | 1153| 6800101 | Parameter verification failed. | 1154 1155**示例：** 1156 1157```ts 1158// 取消该事件的所有监听。 1159audioVolumeManager.off('appVolumeChangeForUid'); 1160 1161// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 1162let appVolumeChangeForUidCallback = (volumeEvent: audio.VolumeEvent) => { 1163 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 1164 console.info(`Volume level: ${volumeEvent.volume} `); 1165 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 1166}; 1167 1168audioVolumeManager.on('appVolumeChangeForUid', appVolumeChangeForUidCallback); 1169 1170audioVolumeManager.off('appVolumeChangeForUid', appVolumeChangeForUidCallback); 1171``` 1172 1173### on('activeVolumeTypeChange')<sup>20+</sup> 1174 1175on(type: 'activeVolumeTypeChange', callback: Callback\<AudioVolumeType>): void 1176 1177监听当前活跃流变化事件（当活跃流发生变化时触发）。使用callback异步回调。 1178 1179**系统接口：** 该接口为系统接口。 1180 1181**系统能力：** SystemCapability.Multimedia.Audio.Volume 1182 1183**参数：** 1184 1185| 参数名 | 类型 | 必填 | 说明 | 1186| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 1187| type | string | 是 | 事件回调类型，支持的事件为'activeVolumeTypeChange'，当活跃流发生变化时，触发该事件。 | 1188| callback | Callback\<[AudioVolumeType](arkts-apis-audio-e.md#audiovolumetype)> | 是 | 回调函数，返回变化后的活跃流类型。 | 1189 1190**错误码：** 1191 1192以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1193 1194| 错误码ID | 错误信息 | 1195| ------- | --------------------------------------------| 1196| 202 | Not system App. | 1197| 6800101 | Parameter verification failed. | 1198 1199**示例：** 1200 1201```ts 1202audioVolumeManager.on('activeVolumeTypeChange', (volumeType: audio.AudioVolumeType) => { 1203 console.info(`VolumeType of stream: ${volumeType} `); 1204}); 1205``` 1206 1207### off('activeVolumeTypeChange')<sup>20+</sup> 1208 1209off(type: 'activeVolumeTypeChange', callback?: Callback\<AudioVolumeType>): void 1210 1211取消监听当前活跃流变化事件。使用callback异步回调。 1212 1213**系统接口：** 该接口为系统接口。 1214 1215**系统能力：** SystemCapability.Multimedia.Audio.Volume 1216 1217**参数：** 1218 1219| 参数名 | 类型 | 必填 | 说明 | 1220| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 1221| type | string | 是 | 事件回调类型，支持的事件为'activeVolumeTypeChange'，当取消监听当前活跃流变化事件时，触发该事件。 | 1222| callback | Callback\<[AudioVolumeType](arkts-apis-audio-e.md#audiovolumetype)> | 否 | 回调函数，返回变化后的活跃流类型。 | 1223 1224**错误码：** 1225 1226以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1227 1228| 错误码ID | 错误信息 | 1229| ------- | --------------------------------------------| 1230| 202 | Not system App. | 1231| 6800101 | Parameter verification failed. | 1232 1233**示例：** 1234 1235```ts 1236// 取消该事件的所有监听。 1237audioVolumeManager.off('activeVolumeTypeChange'); 1238 1239// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 1240let activeVolumeTypeChangeCallback = (volumeType: audio.AudioVolumeType) => { 1241 console.info(`VolumeType of stream: ${volumeType} `); 1242}; 1243 1244audioVolumeManager.on('activeVolumeTypeChange', activeVolumeTypeChangeCallback); 1245 1246audioVolumeManager.off('activeVolumeTypeChange', activeVolumeTypeChangeCallback); 1247``` 1248 1249## AudioVolumeGroupManager<sup>9+</sup> 1250 1251管理音频组音量。在调用AudioVolumeGroupManager的接口前，需要先通过 [getVolumeGroupManager](arkts-apis-audio-AudioVolumeManager.md#getvolumegroupmanager9) 创建实例。 1252 1253### setVolume<sup>9+</sup> 1254 1255setVolume(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback<void>): void 1256 1257设置指定流的音量。使用callback异步回调。 1258 1259**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1260 1261仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 1262 1263**系统接口：** 该接口为系统接口。 1264 1265**系统能力：** SystemCapability.Multimedia.Audio.Volume 1266 1267**参数：** 1268 1269| 参数名 | 类型 | 必填 | 说明 | 1270| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1271| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 1272| volume | number | 是 | 音量等级，可设置范围通过[getMinVolume](arkts-apis-audio-AudioVolumeGroupManager.md#getminvolumedeprecated)和[getMaxVolume](arkts-apis-audio-AudioVolumeGroupManager.md#getmaxvolumedeprecated)获取。 | 1273| callback | AsyncCallback<void> | 是 | 回调函数。当设置指定流的音量成功，err为undefined，否则为错误对象。 | 1274 1275**示例：** 1276 1277```ts 1278import { BusinessError } from '@kit.BasicServicesKit'; 1279 1280audioVolumeGroupManager.setVolume(audio.AudioVolumeType.MEDIA, 10, (err: BusinessError) => { 1281 if (err) { 1282 console.error(`Failed to set the volume. ${err}`); 1283 return; 1284 } 1285 console.info('Callback invoked to indicate a successful volume setting.'); 1286}); 1287``` 1288 1289### setVolume<sup>9+</sup> 1290 1291setVolume(volumeType: AudioVolumeType, volume: number): Promise<void> 1292 1293设置指定流的音量。使用Promise异步回调。 1294 1295**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1296 1297仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 1298 1299**系统接口：** 该接口为系统接口。 1300 1301**系统能力：** SystemCapability.Multimedia.Audio.Volume 1302 1303**参数：** 1304 1305| 参数名 | 类型 | 必填 | 说明 | 1306| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1307| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 1308| volume | number | 是 | 音量等级，可设置范围通过[getMinVolume](arkts-apis-audio-AudioVolumeGroupManager.md#getminvolumedeprecated)和[getMaxVolume](arkts-apis-audio-AudioVolumeGroupManager.md#getmaxvolumedeprecated)获取。 | 1309 1310**返回值：** 1311 1312| 类型 | 说明 | 1313| ------------------- | ----------------------------- | 1314| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1315 1316**示例：** 1317 1318```ts 1319audioVolumeGroupManager.setVolume(audio.AudioVolumeType.MEDIA, 10).then(() => { 1320 console.info('Promise returned to indicate a successful volume setting.'); 1321}); 1322``` 1323 1324### setVolumeWithFlag<sup>12+</sup> 1325 1326setVolumeWithFlag(volumeType: AudioVolumeType, volume: number, flags: number): Promise<void> 1327 1328设置指定流的音量，同时指定本次修改音量是否要显示系统音量条。使用Promise异步回调。 1329 1330**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1331 1332仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 1333 1334**系统接口：** 该接口为系统接口。 1335 1336**系统能力：** SystemCapability.Multimedia.Audio.Volume 1337 1338**参数：** 1339 1340| 参数名 | 类型 | 必填 | 说明 | 1341| ---------- | ----------------------------------- | ---- |--------------------------------------| 1342| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 1343| volume | number | 是 | 音量等级，可设置范围通过[getMinVolume](arkts-apis-audio-AudioVolumeGroupManager.md#getminvolumedeprecated)和[getMaxVolume](arkts-apis-audio-AudioVolumeGroupManager.md#getmaxvolumedeprecated)获取。 | 1344| flags | number | 是 | 是否需要显示系统音量条，0为不需要显示，1为需要显示。 | 1345 1346**返回值：** 1347 1348| 类型 | 说明 | 1349| ------------------- | ----------------------------- | 1350| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1351 1352**错误码：** 1353 1354以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1355 1356| 错误码ID | 错误信息 | 1357| ------- | --------------------------------------------| 1358| 201 | Permission denied. | 1359| 202 | Not system App. | 1360 1361**示例：** 1362 1363```ts 1364audioVolumeGroupManager.setVolumeWithFlag(audio.AudioVolumeType.MEDIA, 10, 1).then(() => { 1365 console.info('Promise returned to indicate a successful volume setting.'); 1366}); 1367``` 1368 1369### mute<sup>9+</sup> 1370 1371mute(volumeType: AudioVolumeType, mute: boolean, callback: AsyncCallback<void>): void 1372 1373设置指定音量流静音。使用callback异步回调。 1374 1375**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1376 1377仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 1378 1379**系统接口：** 该接口为系统接口。 1380 1381**系统能力：** SystemCapability.Multimedia.Audio.Volume 1382 1383**参数：** 1384 1385| 参数名 | 类型 | 必填 | 说明 | 1386| ---------- | ----------------------------------- | ---- | ------------------------------------- | 1387| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 1388| mute | boolean | 是 | 静音状态，true为静音，false为非静音。 | 1389| callback | AsyncCallback<void> | 是 | 回调函数。当设置指定音量流静音成功，err为undefined，否则为错误对象。 | 1390 1391**示例：** 1392 1393```ts 1394import { BusinessError } from '@kit.BasicServicesKit'; 1395 1396audioVolumeGroupManager.mute(audio.AudioVolumeType.MEDIA, true, (err: BusinessError) => { 1397 if (err) { 1398 console.error(`Failed to mute the stream. ${err}`); 1399 return; 1400 } 1401 console.info('Callback invoked to indicate that the stream is muted.'); 1402}); 1403``` 1404 1405### mute<sup>9+</sup> 1406 1407mute(volumeType: AudioVolumeType, mute: boolean): Promise<void> 1408 1409设置指定音量流静音。使用Promise异步回调。 1410 1411**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1412 1413仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 1414 1415**系统接口：** 该接口为系统接口。 1416 1417**系统能力：** SystemCapability.Multimedia.Audio.Volume 1418 1419**参数：** 1420 1421| 参数名 | 类型 | 必填 | 说明 | 1422| ---------- | ----------------------------------- | ---- | ------------------------------------- | 1423| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 1424| mute | boolean | 是 | 静音状态，true为静音，false为非静音。 | 1425 1426**返回值：** 1427 1428| 类型 | 说明 | 1429| ------------------- | ----------------------------- | 1430| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1431 1432**示例：** 1433 1434```ts 1435audioVolumeGroupManager.mute(audio.AudioVolumeType.MEDIA, true).then(() => { 1436 console.info('Promise returned to indicate that the stream is muted.'); 1437}); 1438``` 1439 1440### setRingerMode<sup>9+</sup> 1441 1442setRingerMode(mode: AudioRingMode, callback: AsyncCallback<void>): void 1443 1444设置铃声模式。使用callback异步回调。 1445 1446**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1447 1448仅在静音和非静音状态切换时需要该权限。 1449 1450**系统接口：** 该接口为系统接口。 1451 1452**系统能力：** SystemCapability.Multimedia.Audio.Volume 1453 1454**参数：** 1455 1456| 参数名 | 类型 | 必填 | 说明 | 1457| -------- | ------------------------------- | ---- | ------------------------ | 1458| mode | [AudioRingMode](arkts-apis-audio-e.md#audioringmode) | 是 | 音频铃声模式。 | 1459| callback | AsyncCallback<void> | 是 | 回调函数。当设置铃声模式成功，err为undefined，否则为错误对象。 | 1460 1461**示例：** 1462 1463```ts 1464import { BusinessError } from '@kit.BasicServicesKit'; 1465 1466audioVolumeGroupManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL, (err: BusinessError) => { 1467 if (err) { 1468 console.error(`Failed to set the ringer mode. ${err}`); 1469 return; 1470 } 1471 console.info('Callback invoked to indicate a successful setting of the ringer mode.'); 1472}); 1473``` 1474 1475### setRingerMode<sup>9+</sup> 1476 1477setRingerMode(mode: AudioRingMode): Promise<void> 1478 1479设置铃声模式。使用Promise异步回调。 1480 1481**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1482 1483仅在静音和非静音状态切换时需要该权限。 1484 1485**系统接口：** 该接口为系统接口。 1486 1487**系统能力：** SystemCapability.Multimedia.Audio.Volume 1488 1489**参数：** 1490 1491| 参数名 | 类型 | 必填 | 说明 | 1492| ------ | ------------------------------- | ---- | -------------- | 1493| mode | [AudioRingMode](arkts-apis-audio-e.md#audioringmode) | 是 | 音频铃声模式。 | 1494 1495**返回值：** 1496 1497| 类型 | 说明 | 1498| ------------------- | ------------------------------- | 1499| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1500 1501**示例：** 1502 1503```ts 1504audioVolumeGroupManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL).then(() => { 1505 console.info('Promise returned to indicate a successful setting of the ringer mode.'); 1506}); 1507``` 1508 1509### setMicMute<sup>11+</sup> 1510 1511setMicMute(mute: boolean): Promise<void> 1512 1513设置麦克风静音状态。使用Promise异步回调。 1514 1515**需要权限：** ohos.permission.MANAGE_AUDIO_CONFIG 1516 1517**系统接口：** 该接口为系统接口。 1518 1519**系统能力：** SystemCapability.Multimedia.Audio.Volume 1520 1521**参数：** 1522 1523| 参数名 | 类型 | 必填 | 说明 | 1524| ------ | ------- | ---- | --------------------------------------------- | 1525| mute | boolean | 是 | 待设置的静音状态，true为静音，false为非静音。 | 1526 1527**返回值：** 1528 1529| 类型 | 说明 | 1530| ------------------- | ------------------------------- | 1531| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1532 1533**错误码：** 1534 1535以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1536 1537| 错误码ID | 错误信息 | 1538| ------- | --------------------------------------------| 1539| 201 | Permission denied. | 1540| 202 | Not system App. | 1541| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1542| 6800101 | Parameter verification failed. | 1543 1544**示例：** 1545 1546```ts 1547audioVolumeGroupManager.setMicMute(true).then(() => { 1548 console.info('Promise returned to indicate that the mic is muted.'); 1549}); 1550``` 1551 1552### adjustVolumeByStep<sup>10+</sup> 1553 1554adjustVolumeByStep(adjustType: VolumeAdjustType, callback: AsyncCallback<void>): void 1555 1556调节当前最高优先级的流的音量，使音量值按步长加或减。使用callback异步回调。 1557 1558**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1559 1560仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 1561 1562**系统接口：** 该接口为系统接口。 1563 1564**系统能力：** SystemCapability.Multimedia.Audio.Volume 1565 1566**参数：** 1567 1568| 参数名 | 类型 | 必填 | 说明 | 1569| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1570| adjustType | [VolumeAdjustType](#volumeadjusttype10) | 是 | 音量调节方向。 | 1571| callback | AsyncCallback<void> | 是 | 回调函数。当调节当前最高优先级的流的音量成功，err为undefined，否则为错误对象。 | 1572 1573**错误码：** 1574 1575以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1576 1577| 错误码ID | 错误信息 | 1578| ------- | --------------------------------------------| 1579| 201 | Permission denied. | 1580| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1581| 6800101 | Parameter verification failed. Return by callback. | 1582| 6800301 | System error. Return by callback. | 1583 1584**示例：** 1585 1586```ts 1587import { BusinessError } from '@kit.BasicServicesKit'; 1588 1589audioVolumeGroupManager.adjustVolumeByStep(audio.VolumeAdjustType.VOLUME_UP, (err: BusinessError) => { 1590 if (err) { 1591 console.error(`Failed to adjust the volume by step. ${err}`); 1592 return; 1593 } else { 1594 console.info('Success to adjust the volume by step.'); 1595 } 1596}); 1597``` 1598### adjustVolumeByStep<sup>10+</sup> 1599 1600adjustVolumeByStep(adjustType: VolumeAdjustType): Promise<void> 1601 1602单步设置当前最高优先级的流的音量。使用Promise异步回调。 1603 1604**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1605 1606仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 1607 1608**系统接口：** 该接口为系统接口。 1609 1610**系统能力：** SystemCapability.Multimedia.Audio.Volume 1611 1612**参数：** 1613 1614| 参数名 | 类型 | 必填 | 说明 | 1615| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1616| adjustType | [VolumeAdjustType](#volumeadjusttype10) | 是 | 音量调节方向。 | 1617 1618**返回值：** 1619 1620| 类型 | 说明 | 1621| ------------------- | ----------------------------- | 1622| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1623 1624**错误码：** 1625 1626以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1627 1628| 错误码ID | 错误信息 | 1629| ------- | --------------------------------------------| 1630| 201 | Permission denied. | 1631| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1632| 6800101 | Parameter verification failed. Return by promise. | 1633| 6800301 | System error. Return by promise. | 1634 1635**示例：** 1636 1637```ts 1638import { BusinessError } from '@kit.BasicServicesKit'; 1639 1640audioVolumeGroupManager.adjustVolumeByStep(audio.VolumeAdjustType.VOLUME_UP).then(() => { 1641 console.info('Success to adjust the volume by step.'); 1642}).catch((error: BusinessError) => { 1643 console.error('Fail to adjust the volume by step.'); 1644}); 1645``` 1646 1647### adjustSystemVolumeByStep<sup>10+</sup> 1648 1649adjustSystemVolumeByStep(volumeType: AudioVolumeType, adjustType: VolumeAdjustType, callback: AsyncCallback<void>): void 1650 1651单步设置指定流的音量。使用callback异步回调。 1652 1653**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1654 1655仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 1656 1657**系统接口：** 该接口为系统接口。 1658 1659**系统能力：** SystemCapability.Multimedia.Audio.Volume 1660 1661**参数：** 1662 1663| 参数名 | 类型 | 必填 | 说明 | 1664| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1665| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 1666| adjustType | [VolumeAdjustType](#volumeadjusttype10) | 是 | 音量调节方向。 | 1667| callback | AsyncCallback<void> | 是 | 回调函数。当单步设置指定流的音量成功，err为undefined，否则为错误对象。 | 1668 1669**错误码：** 1670 1671以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1672 1673| 错误码ID | 错误信息 | 1674| ------- | --------------------------------------------| 1675| 201 | Permission denied. | 1676| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1677| 6800101 | Parameter verification failed. Return by callback. | 1678| 6800301 | System error. Return by callback. | 1679 1680**示例：** 1681 1682```ts 1683import { BusinessError } from '@kit.BasicServicesKit'; 1684 1685audioVolumeGroupManager.adjustSystemVolumeByStep(audio.AudioVolumeType.MEDIA, audio.VolumeAdjustType.VOLUME_UP, (err: BusinessError) => { 1686 if (err) { 1687 console.error(`Failed to adjust the system volume by step ${err}`); 1688 } else { 1689 console.info('Success to adjust the system volume by step.'); 1690 } 1691}); 1692``` 1693### adjustSystemVolumeByStep<sup>10+</sup> 1694 1695adjustSystemVolumeByStep(volumeType: AudioVolumeType, adjustType: VolumeAdjustType): Promise<void> 1696 1697单步设置指定流的音量。使用Promise异步回调。 1698 1699**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1700 1701仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 1702 1703**系统接口：** 该接口为系统接口。 1704 1705**系统能力：** SystemCapability.Multimedia.Audio.Volume 1706 1707**参数：** 1708 1709| 参数名 | 类型 | 必填 | 说明 | 1710| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1711| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 1712| adjustType | [VolumeAdjustType](#volumeadjusttype10) | 是 | 音量调节方向。 | 1713 1714**返回值：** 1715 1716| 类型 | 说明 | 1717| ------------------- | ----------------------------- | 1718| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1719 1720**错误码：** 1721 1722以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1723 1724| 错误码ID | 错误信息 | 1725| -------- | --------------------------------------------| 1726| 201 | Permission denied. | 1727| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1728| 6800101 | Parameter verification failed. Return by promise. | 1729| 6800301 | System error. Return by promise. | 1730 1731**示例：** 1732 1733```ts 1734import { BusinessError } from '@kit.BasicServicesKit'; 1735 1736audioVolumeGroupManager.adjustSystemVolumeByStep(audio.AudioVolumeType.MEDIA, audio.VolumeAdjustType.VOLUME_UP).then(() => { 1737 console.info('Success to adjust the system volume by step.'); 1738}).catch((error: BusinessError) => { 1739 console.error('Fail to adjust the system volume by step.'); 1740}); 1741``` 1742## AudioEffectManager<sup>18+</sup> 1743 1744音频效果管理。在使用AudioEffectManager的接口前，需要使用[getEffectManager](#geteffectmanager18)获取AudioEffectManager实例。 1745 1746 1747### getSupportedAudioEffectProperty<sup>18+</sup> 1748 1749getSupportedAudioEffectProperty(): Array\<AudioEffectProperty> 1750 1751获取支持的下行音效模式，同步返回结果。 1752 1753**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 1754 1755**系统接口：** 该接口为系统接口。 1756 1757**系统能力：** SystemCapability.Multimedia.Audio.Core 1758 1759**返回值：** 1760 1761| 类型 | 说明 | 1762| --------------------------------------------------------------------------| --------------------------------------- | 1763| Array\<[AudioEffectProperty](#audioeffectproperty18)> | 返回当前设备支持的音效模式。 | 1764 1765**错误码：** 1766 1767以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1768 1769| 错误码ID | 错误信息 | 1770| ------- | --------------------------------------------| 1771| 201 | Permission denied. | 1772| 202 | Caller is not a system application. | 1773| 6800301 | System error. Return by callback. | 1774 1775**示例：** 1776 1777```ts 1778import { BusinessError } from '@kit.BasicServicesKit'; 1779 1780try { 1781 let propertyArray: Array<audio.AudioEffectProperty> = audioStreamManager.getSupportedAudioEffectProperty(); 1782 console.info(`The effect modes are: ${propertyArray}`); 1783} catch (err) { 1784 let error = err as BusinessError; 1785 console.error(`getSupportedAudioEffectProperty ERROR: ${error}`); 1786} 1787``` 1788 1789 1790### getAudioEffectProperty<sup>18+</sup> 1791 1792getAudioEffectProperty(): Array\<AudioEffectProperty> 1793 1794获取当前音效模式，同步返回结果。 1795 1796**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 1797 1798**系统接口：** 该接口为系统接口。 1799 1800**系统能力：** SystemCapability.Multimedia.Audio.Core 1801 1802**返回值：** 1803 1804| 类型 | 说明 | 1805| --------------------------------------------------------------------------| --------------------------------------- | 1806| Array\<[AudioEffectProperty](#audioeffectproperty18)> | 返回当前音效模式。 | 1807 1808**错误码：** 1809 1810以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1811 1812| 错误码ID | 错误信息 | 1813| ------- | --------------------------------------------| 1814| 201 | Permission denied. | 1815| 202 | Caller is not a system application. | 1816| 6800301 | System error. Return by callback. | 1817 1818**示例：** 1819 1820```ts 1821import { BusinessError } from '@kit.BasicServicesKit'; 1822 1823try { 1824 let propertyArray: Array<audio.AudioEffectProperty> = audioStreamManager.getAudioEffectProperty(); 1825 console.info(`The effect modes are: ${propertyArray}`); 1826} catch (err) { 1827 let error = err as BusinessError; 1828 console.error(`getAudioEffectProperty ERROR: ${error}`); 1829} 1830``` 1831 1832### setAudioEffectProperty<sup>18+</sup> 1833 1834setAudioEffectProperty(propertyArray: Array\<AudioEffectProperty>): void 1835 1836设置当前音效模式，同步返回结果。 1837 1838**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 1839 1840**系统接口：** 该接口为系统接口。 1841 1842**系统能力：** SystemCapability.Multimedia.Audio.core 1843 1844**参数：** 1845 1846| 参数名 | 类型 | 必填 | 说明 | 1847| ------------- | ----------------------------------------------------- | -------- | ---------------------------- | 1848| propertyArray | Array\<[AudioEffectProperty](#audioeffectproperty18)> | 是 | 需要设置的音效模式。 | 1849 1850**错误码：** 1851 1852以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 1853 1854| 错误码ID | 错误信息 | 1855| ------- | --------------------------------------------| 1856| 201 | Permission denied. | 1857| 202 | Caller is not a system application. | 1858| 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.| 1859| 6800301 | System error. Return by callback. | 1860 1861**示例：** 1862 1863```ts 1864import { BusinessError } from '@kit.BasicServicesKit'; 1865 1866try { 1867 let propertyArray: Array<audio.AudioEffectProperty> = audioEffectManager.getAudioEffectProperty(); 1868 console.info(`The effect modes are: ${propertyArray}`); 1869 audioEffectManager.setAudioEffectProperty(propertyArray); 1870} catch (err) { 1871 let error = err as BusinessError; 1872 console.error(`setAudioEffectProperty ERROR: ${error}`); 1873} 1874``` 1875 1876## AudioRoutingManager<sup>9+</sup> 1877 1878音频路由管理。在使用AudioRoutingManager的接口前，需要使用[getRoutingManager](arkts-apis-audio-AudioManager.md#getroutingmanager9)获取AudioRoutingManager实例。 1879 1880### selectInputDevice<sup>9+</sup> 1881 1882selectInputDevice(inputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void 1883 1884选择音频输入设备，当前只能选择一个输入设备。使用callback异步回调。 1885 1886**系统接口：** 该接口为系统接口。 1887 1888**系统能力：** SystemCapability.Multimedia.Audio.Device 1889 1890**参数：** 1891 1892| 参数名 | 类型 | 必填 | 说明 | 1893| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1894| inputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输入设备类。 | 1895| callback | AsyncCallback<void> | 是 | 回调函数。当选择音频输入设备成功，err为undefined，否则为错误对象。 | 1896 1897**示例：** 1898```ts 1899import { audio } from '@kit.AudioKit'; 1900import { BusinessError } from '@kit.BasicServicesKit'; 1901 1902let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1903 deviceRole : audio.DeviceRole.INPUT_DEVICE, 1904 deviceType : audio.DeviceType.MIC, 1905 id : 1, 1906 name : "", 1907 address : "", 1908 sampleRates : [44100], 1909 channelCounts : [2], 1910 channelMasks : [0], 1911 networkId : audio.LOCAL_NETWORK_ID, 1912 interruptGroupId : 1, 1913 volumeGroupId : 1, 1914 displayName : "", 1915}]; 1916 1917async function selectInputDevice(){ 1918 audioRoutingManager.selectInputDevice(inputAudioDeviceDescriptor, (err: BusinessError) => { 1919 if (err) { 1920 console.error(`Result ERROR: ${err}`); 1921 } else { 1922 console.info('Select input devices result callback: SUCCESS'); 1923 } 1924 }); 1925} 1926``` 1927 1928### selectInputDevice<sup>9+</sup> 1929 1930selectInputDevice(inputAudioDevices: AudioDeviceDescriptors): Promise<void> 1931 1932选择音频输入设备，当前只能选择一个输入设备。使用Promise异步回调。 1933 1934**系统接口：** 该接口为系统接口。 1935 1936**系统能力：** SystemCapability.Multimedia.Audio.Device 1937 1938**参数：** 1939 1940| 参数名 | 类型 | 必填 | 说明 | 1941| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1942| inputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输入设备类。 | 1943 1944**返回值：** 1945 1946| 类型 | 说明 | 1947| --------------------- | --------------------------- | 1948| Promise<void> | Promise对象。无返回结果的Promise对象。 | 1949 1950**示例：** 1951 1952```ts 1953import { audio } from '@kit.AudioKit'; 1954import { BusinessError } from '@kit.BasicServicesKit'; 1955 1956let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1957 deviceRole : audio.DeviceRole.INPUT_DEVICE, 1958 deviceType : audio.DeviceType.MIC, 1959 id : 1, 1960 name : "", 1961 address : "", 1962 sampleRates : [44100], 1963 channelCounts : [2], 1964 channelMasks : [0], 1965 networkId : audio.LOCAL_NETWORK_ID, 1966 interruptGroupId : 1, 1967 volumeGroupId : 1, 1968 displayName : "", 1969}]; 1970 1971async function getRoutingManager(){ 1972 audioRoutingManager.selectInputDevice(inputAudioDeviceDescriptor).then(() => { 1973 console.info('Select input devices result promise: SUCCESS'); 1974 }).catch((err: BusinessError) => { 1975 console.error(`Result ERROR: ${err}`); 1976 }); 1977} 1978``` 1979 1980### selectOutputDevice<sup>9+</sup> 1981 1982selectOutputDevice(outputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void 1983 1984选择音频输出设备，当前只能选择一个输出设备。使用callback异步回调。 1985 1986**系统接口：** 该接口为系统接口。 1987 1988**系统能力：** SystemCapability.Multimedia.Audio.Device 1989 1990**参数：** 1991 1992| 参数名 | 类型 | 必填 | 说明 | 1993| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1994| outputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输出设备类。 | 1995| callback | AsyncCallback<void> | 是 | 回调函数。当选择音频输出设备成功，err为undefined，否则为错误对象。 | 1996 1997**示例：** 1998```ts 1999import { audio } from '@kit.AudioKit'; 2000import { BusinessError } from '@kit.BasicServicesKit'; 2001 2002let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 2003 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2004 deviceType : audio.DeviceType.SPEAKER, 2005 id : 1, 2006 name : "", 2007 address : "", 2008 sampleRates : [44100], 2009 channelCounts : [2], 2010 channelMasks : [0], 2011 networkId : audio.LOCAL_NETWORK_ID, 2012 interruptGroupId : 1, 2013 volumeGroupId : 1, 2014 displayName : "", 2015}]; 2016 2017async function selectOutputDevice(){ 2018 audioRoutingManager.selectOutputDevice(outputAudioDeviceDescriptor, (err: BusinessError) => { 2019 if (err) { 2020 console.error(`Result ERROR: ${err}`); 2021 } else { 2022 console.info('Select output devices result callback: SUCCESS'); } 2023 }); 2024} 2025``` 2026 2027### selectOutputDevice<sup>9+</sup> 2028 2029selectOutputDevice(outputAudioDevices: AudioDeviceDescriptors): Promise<void> 2030 2031选择音频输出设备，当前只能选择一个输出设备。使用Promise异步回调。 2032 2033**系统接口：** 该接口为系统接口。 2034 2035**系统能力：** SystemCapability.Multimedia.Audio.Device 2036 2037**参数：** 2038 2039| 参数名 | 类型 | 必填 | 说明 | 2040| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 2041| outputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输出设备类。 | 2042 2043**返回值：** 2044 2045| 类型 | 说明 | 2046| --------------------- | --------------------------- | 2047| Promise<void> | Promise对象。无返回结果的Promise对象。 | 2048 2049**示例：** 2050 2051```ts 2052import { audio } from '@kit.AudioKit'; 2053import { BusinessError } from '@kit.BasicServicesKit'; 2054 2055let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 2056 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2057 deviceType : audio.DeviceType.SPEAKER, 2058 id : 1, 2059 name : "", 2060 address : "", 2061 sampleRates : [44100], 2062 channelCounts : [2], 2063 channelMasks : [0], 2064 networkId : audio.LOCAL_NETWORK_ID, 2065 interruptGroupId : 1, 2066 volumeGroupId : 1, 2067 displayName : "", 2068}]; 2069 2070async function selectOutputDevice(){ 2071 audioRoutingManager.selectOutputDevice(outputAudioDeviceDescriptor).then(() => { 2072 console.info('Select output devices result promise: SUCCESS'); 2073 }).catch((err: BusinessError) => { 2074 console.error(`Result ERROR: ${err}`); 2075 }); 2076} 2077``` 2078 2079### selectOutputDeviceByFilter<sup>9+</sup> 2080 2081selectOutputDeviceByFilter(filter: AudioRendererFilter, outputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void 2082 2083根据过滤条件，选择音频输出设备，当前只能选择一个输出设备。使用callback异步回调。 2084 2085**系统接口：** 该接口为系统接口。 2086 2087**系统能力：** SystemCapability.Multimedia.Audio.Device 2088 2089**参数：** 2090 2091| 参数名 | 类型 | 必填 | 说明 | 2092| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 2093| filter | [AudioRendererFilter](#audiorendererfilter9) | 是 | 过滤条件类。 | 2094| outputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输出设备类。 | 2095| callback | AsyncCallback<void> | 是 | 回调函数。当选择音频输出设备成功，err为undefined，否则为错误对象。 | 2096 2097**示例：** 2098```ts 2099import { audio } from '@kit.AudioKit'; 2100import { BusinessError } from '@kit.BasicServicesKit'; 2101 2102let outputAudioRendererFilter: audio.AudioRendererFilter = { 2103 uid : 20010041, 2104 rendererInfo : { 2105 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 2106 rendererFlags : 0 2107 }, 2108 rendererId : 0 2109}; 2110 2111let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 2112 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2113 deviceType : audio.DeviceType.SPEAKER, 2114 id : 1, 2115 name : "", 2116 address : "", 2117 sampleRates : [44100], 2118 channelCounts : [2], 2119 channelMasks : [0], 2120 networkId : audio.LOCAL_NETWORK_ID, 2121 interruptGroupId : 1, 2122 volumeGroupId : 1, 2123 displayName : "", 2124}]; 2125 2126async function selectOutputDeviceByFilter(){ 2127 audioRoutingManager.selectOutputDeviceByFilter(outputAudioRendererFilter, outputAudioDeviceDescriptor, (err: BusinessError) => { 2128 if (err) { 2129 console.error(`Result ERROR: ${err}`); 2130 } else { 2131 console.info('Select output devices by filter result callback: SUCCESS'); } 2132 }); 2133} 2134``` 2135 2136### selectOutputDeviceByFilter<sup>9+</sup> 2137 2138selectOutputDeviceByFilter(filter: AudioRendererFilter, outputAudioDevices: AudioDeviceDescriptors): Promise<void> 2139 2140根据过滤条件，选择音频输出设备，当前只能选择一个输出设备。使用Promise异步回调。 2141 2142**系统接口：** 该接口为系统接口。 2143 2144**系统能力：** SystemCapability.Multimedia.Audio.Device 2145 2146**参数：** 2147 2148| 参数名 | 类型 | 必填 | 说明 | 2149| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 2150| filter | [AudioRendererFilter](#audiorendererfilter9) | 是 | 过滤条件类。 | 2151| outputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输出设备类。 | 2152 2153**返回值：** 2154 2155| 类型 | 说明 | 2156| --------------------- | --------------------------- | 2157| Promise<void> | Promise对象。无返回结果的Promise对象。 | 2158 2159**示例：** 2160 2161```ts 2162import { audio } from '@kit.AudioKit'; 2163import { BusinessError } from '@kit.BasicServicesKit'; 2164 2165let outputAudioRendererFilter: audio.AudioRendererFilter = { 2166 uid : 20010041, 2167 rendererInfo : { 2168 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 2169 rendererFlags : 0 2170 }, 2171 rendererId : 0 2172}; 2173 2174let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 2175 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2176 deviceType : audio.DeviceType.SPEAKER, 2177 id : 1, 2178 name : "", 2179 address : "", 2180 sampleRates : [44100], 2181 channelCounts : [2], 2182 channelMasks : [0], 2183 networkId : audio.LOCAL_NETWORK_ID, 2184 interruptGroupId : 1, 2185 volumeGroupId : 1, 2186 displayName : "", 2187}]; 2188 2189async function selectOutputDeviceByFilter(){ 2190 audioRoutingManager.selectOutputDeviceByFilter(outputAudioRendererFilter, outputAudioDeviceDescriptor).then(() => { 2191 console.info('Select output devices by filter result promise: SUCCESS'); 2192 }).catch((err: BusinessError) => { 2193 console.error(`Result ERROR: ${err}`); 2194 }) 2195} 2196``` 2197 2198### selectInputDeviceByFilter<sup>18+</sup> 2199 2200selectInputDeviceByFilter(filter: AudioCapturerFilter, inputAudioDevices: AudioDeviceDescriptors): Promise<void> 2201 2202根据过滤条件，选择音频输入设备，当前只能选择一个输入设备。使用Promise异步回调。 2203 2204**系统接口：** 该接口为系统接口。 2205 2206**系统能力：** SystemCapability.Multimedia.Audio.Device 2207 2208**参数：** 2209 2210| 参数名 | 类型 | 必填 | 说明 | 2211| ----------------------|-------------------------------------------------------------------| ---- |--------| 2212| filter | [AudioCapturerFilter](#audiocapturerfilter18) | 是 | 过滤条件类。 | 2213| inputAudioDevices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 输入设备类。 | 2214 2215**返回值：** 2216 2217| 类型 | 说明 | 2218| --------------------- | --------------------------- | 2219| Promise<void> | Promise对象。无返回结果的Promise对象。 | 2220 2221**错误码：** 2222 2223以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 2224 2225| 错误码ID | 错误信息 | 2226| ------- | --------------------------------------------| 2227| 202 | Not system App. | 2228| 6800101 | Parameter verification failed.| 2229 2230 2231**示例：** 2232 2233```ts 2234import { audio } from '@kit.AudioKit'; 2235import { BusinessError } from '@kit.BasicServicesKit'; 2236 2237let inputAudioCapturerFilter: audio.AudioCapturerFilter = { 2238 uid : 20010041, 2239 capturerInfo : { 2240 source: audio.SourceType.SOURCE_TYPE_MIC, 2241 capturerFlags: 0 2242 } 2243}; 2244 2245let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 2246 deviceRole : audio.DeviceRole.INPUT_DEVICE, 2247 deviceType : audio.DeviceType.MIC, 2248 id : 1, 2249 name : "", 2250 address : "", 2251 sampleRates : [44100], 2252 channelCounts : [2], 2253 channelMasks : [0], 2254 networkId : audio.LOCAL_NETWORK_ID, 2255 interruptGroupId : 1, 2256 volumeGroupId : 1, 2257 displayName : "", 2258}]; 2259 2260async function selectInputDeviceByFilter(){ 2261 let audioManager = audio.getAudioManager(); // 需要先创建AudioManager实例。 2262 let audioRoutingManager = audioManager.getRoutingManager(); // 再调用AudioManager的方法创建AudioRoutingManager实例。 2263 audioRoutingManager.selectInputDeviceByFilter(inputAudioCapturerFilter, inputAudioDeviceDescriptor).then(() => { 2264 console.info('Select input devices by filter result promise: SUCCESS'); 2265 }).catch((err: BusinessError) => { 2266 console.error(`Result ERROR: ${err}`); 2267 }) 2268} 2269``` 2270 2271### getPreferredOutputDeviceByFilter<sup>18+</sup> 2272 2273getPreferredOutputDeviceByFilter(filter: AudioRendererFilter): AudioDeviceDescriptors 2274 2275根据过滤条件，查询音频输出设备。 2276 2277**系统接口：** 该接口为系统接口。 2278 2279**系统能力：** SystemCapability.Multimedia.Audio.Device 2280 2281**参数：** 2282 2283| 参数名 | 类型 | 必填 | 说明 | 2284| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 2285| filter | [AudioRendererFilter](#audiorendererfilter9) | 是 | 过滤条件类。 | 2286 2287**返回值：** 2288 2289| 类型 | 说明 | 2290| --------------------- | --------------------------- | 2291| [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors)| return the device list. | 2292 2293**错误码：** 2294 2295以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 2296 2297| 错误码ID | 错误信息 | 2298| ------- | --------------------------------------------| 2299| 202 | Not system App. | 2300| 6800101 | Parameter verification failed.| 2301 2302**示例：** 2303```ts 2304import { audio } from '@kit.AudioKit'; 2305import { BusinessError } from '@kit.BasicServicesKit'; 2306 2307let outputAudioRendererFilter: audio.AudioRendererFilter = { 2308 uid : 20010041, 2309 rendererInfo : { 2310 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 2311 rendererFlags : 0 2312 }, 2313 rendererId : 0 2314}; 2315 2316async function selectOutputDeviceByFilter(){ 2317 let audioManager = audio.getAudioManager(); // 需要先创建AudioManager实例。 2318 let audioRoutingManager = audioManager.getRoutingManager(); // 再调用AudioManager的方法创建AudioRoutingManager实例。 2319 let desc : audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredOutputDeviceByFilter(outputAudioRendererFilter); 2320 console.info(`device descriptor: ${desc}`); 2321} 2322``` 2323 2324### getPreferredInputDeviceByFilter<sup>18+</sup> 2325 2326getPreferredInputDeviceByFilter(filter: AudioCapturerFilter): AudioDeviceDescriptors 2327 2328根据过滤条件，查询音频输入设备，当前只能查询一个输入设备。 2329 2330**系统接口：** 该接口为系统接口。 2331 2332**系统能力：** SystemCapability.Multimedia.Audio.Device 2333 2334**参数：** 2335 2336| 参数名 | 类型 | 必填 | 说明 | 2337|---------------------|-----------------------------------------------| ---- | ------------------------- | 2338| filter | [AudioCapturerFilter](#audiocapturerfilter18) | 是 | 过滤条件类。 | 2339 2340**返回值：** 2341 2342| 类型 | 说明 | 2343| --------------------- | --------------------------- | 2344| [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | return the device list. | 2345 2346**错误码：** 2347 2348以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 2349 2350| 错误码ID | 错误信息 | 2351| ------- | --------------------------------------------| 2352| 202 | Not system App. | 2353| 6800101 | Parameter verification failed.| 2354 2355**示例：** 2356 2357```ts 2358import { audio } from '@kit.AudioKit'; 2359import { BusinessError } from '@kit.BasicServicesKit'; 2360 2361let inputAudioCapturerFilter: audio.AudioCapturerFilter = { 2362 uid : 20010041, 2363 capturerInfo : { 2364 source: audio.SourceType.SOURCE_TYPE_MIC, 2365 capturerFlags: 0 2366 } 2367}; 2368 2369async function getPreferredInputDeviceByFilter(){ 2370 let audioManager = audio.getAudioManager(); // 需要先创建AudioManager实例。 2371 let audioRoutingManager = audioManager.getRoutingManager(); // 再调用AudioManager的方法创建AudioRoutingManager实例。 2372 let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredInputDeviceByFilter(inputAudioCapturerFilter); 2373 console.info(`device descriptor: ${desc}`); 2374} 2375``` 2376 2377### excludeOutputDevices<sup>18+</sup> 2378 2379excludeOutputDevices(usage: DeviceUsage, devices: AudioDeviceDescriptors): Promise<void> 2380 2381排除输出设备。成功调用此函数后，音频将不会在指定的设备上播放。 2382 2383> **说明：** 2384> 2385> 该功能仅能排除外部输出设备，不支持本地输出设备。 2386 2387**需要权限：** ohos.permission.MANAGE_AUDIO_CONFIG 2388 2389**系统接口：** 该接口为系统接口。 2390 2391**系统能力：** SystemCapability.Multimedia.Audio.Device 2392 2393**参数：** 2394 2395| 参数名 | 类型 | 必填 | 说明 | 2396| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 2397| usage | [DeviceUsage](arkts-apis-audio-e.md#deviceusage12) | 是 | 设备种类。只支持排除输出设备。 | 2398| devices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 排除输出设备列表。 | 2399 2400**返回值：** 2401 2402| 类型 | 说明 | 2403| --------------------- | --------------------------- | 2404| Promise<void> | Promise对象。无返回结果。 | 2405 2406**错误码：** 2407 2408以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 2409 2410| 错误码ID | 错误信息 | 2411| ------- | --------------------------------------------| 2412| 201 | Permission denied. Return by callback. | 2413| 202 | Not system App. | 2414| 6800101 | Parameter verification failed. | 2415 2416**示例：** 2417 2418```ts 2419import { audio } from '@kit.AudioKit'; 2420import { BusinessError } from '@kit.BasicServicesKit'; 2421 2422let usage: audio.DeviceUsage.MEDIA_OUTPUT_DEVICES; 2423let excludedDevices: audio.AudioDeviceDescriptors = [{ 2424 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2425 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2426 id : 3, 2427 name : "", 2428 address : "", 2429 sampleRates : [44100], 2430 channelCounts : [2], 2431 channelMasks : [0], 2432 networkId : audio.LOCAL_NETWORK_ID, 2433 interruptGroupId : 1, 2434 volumeGroupId : 1, 2435 displayName : "", 2436}]; 2437 2438async function excludeOutputDevices(){ 2439 audioRoutingManager.excludeOutputDevices(usage, excludedDevices, (err: BusinessError) => { 2440 if (err) { 2441 console.error(`Result ERROR: ${err}`); 2442 } else { 2443 console.info('Exclude Output Devices result callback: SUCCESS'); } 2444 }); 2445} 2446``` 2447 2448### unexcludeOutputDevices<sup>18+</sup> 2449 2450unexcludeOutputDevices(usage: DeviceUsage, devices: AudioDeviceDescriptors): Promise<void> 2451 2452解除排除输出设备。成功调用此函数后，音频将会重新选择输出设备。 2453 2454**需要权限：** ohos.permission.MANAGE_AUDIO_CONFIG 2455 2456**系统接口：** 该接口为系统接口。 2457 2458**系统能力：** SystemCapability.Multimedia.Audio.Device 2459 2460**参数：** 2461 2462| 参数名 | 类型 | 必填 | 说明 | 2463| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 2464| usage | [DeviceUsage](arkts-apis-audio-e.md#deviceusage12) | 是 | 设备种类。只支持排除输出设备。 | 2465| devices | [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 是 | 解除排除输出设备列表。 | 2466 2467**返回值：** 2468 2469| 类型 | 说明 | 2470| --------------------- | --------------------------- | 2471| Promise<void> | Promise对象。无返回结果。 | 2472 2473**错误码：** 2474 2475以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 2476 2477| 错误码ID | 错误信息 | 2478| ------- | --------------------------------------------| 2479| 201 | Permission denied. Return by callback. | 2480| 202 | Not system App. | 2481| 6800101 | Parameter verification failed. | 2482 2483**示例：** 2484 2485```ts 2486import { audio } from '@kit.AudioKit'; 2487import { BusinessError } from '@kit.BasicServicesKit'; 2488 2489let usage: audio.DeviceUsage.MEDIA_OUTPUT_DEVICES; 2490let unexcludedDevices: audio.AudioDeviceDescriptors = [{ 2491 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2492 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2493 id : 3, 2494 name : "", 2495 address : "", 2496 sampleRates : [44100], 2497 channelCounts : [2], 2498 channelMasks : [0], 2499 networkId : audio.LOCAL_NETWORK_ID, 2500 interruptGroupId : 1, 2501 volumeGroupId : 1, 2502 displayName : "", 2503}]; 2504 2505async function unexcludeOutputDevices(){ 2506 audioRoutingManager.unexcludeOutputDevices(usage, unexcludedDevices, (err: BusinessError) => { 2507 if (err) { 2508 console.error(`Result ERROR: ${err}`); 2509 } else { 2510 console.info('Unexclude Output Devices result callback: SUCCESS'); } 2511 }); 2512} 2513``` 2514 2515### unexcludeOutputDevices<sup>18+</sup> 2516 2517unexcludeOutputDevices(usage: DeviceUsage): Promise<void> 2518 2519解除属于特定用途的所有输出设备的排除。成功调用此函数后，音频将会重新选择输出设备。 2520 2521**需要权限：** ohos.permission.MANAGE_AUDIO_CONFIG 2522 2523**系统接口：** 该接口为系统接口。 2524 2525**系统能力：** SystemCapability.Multimedia.Audio.Device 2526 2527**参数：** 2528 2529| 参数名 | 类型 | 必填 | 说明 | 2530| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 2531| usage | [DeviceUsage](arkts-apis-audio-e.md#deviceusage12) | 是 | 设备种类。只支持排除输出设备。 | 2532 2533**返回值：** 2534 2535| 类型 | 说明 | 2536| --------------------- | --------------------------- | 2537| Promise<void> | Promise对象。无返回结果。 | 2538 2539**错误码：** 2540 2541以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 2542 2543| 错误码ID | 错误信息 | 2544| ------- | --------------------------------------------| 2545| 201 | Permission denied. Return by callback. | 2546| 202 | Not system App. | 2547| 6800101 | Parameter verification failed. | 2548 2549**示例：** 2550 2551```ts 2552import { audio } from '@kit.AudioKit'; 2553import { BusinessError } from '@kit.BasicServicesKit'; 2554 2555let usage: audio.DeviceUsage.MEDIA_OUTPUT_DEVICES; 2556 2557async function unexcludeOutputDevices(){ 2558 audioRoutingManager.unexcludeOutputDevices(usage).then(() => { 2559 console.info('Unexclude Output Devices result promise: SUCCESS'); 2560 }).catch((err: BusinessError) => { 2561 console.error(`Result ERROR: ${err}`); 2562 }); 2563} 2564``` 2565 2566### getExcludedDevices<sup>18+</sup> 2567 2568getExcludedDevices(usage: DeviceUsage): AudioDeviceDescriptors 2569 2570获取排除输出设备列表。 2571 2572**需要权限：** ohos.permission.MANAGE_AUDIO_CONFIG 2573 2574**系统接口：** 该接口为系统接口。 2575 2576**系统能力：** SystemCapability.Multimedia.Audio.Device 2577 2578**参数：** 2579 2580| 参数名 | 类型 | 必填 | 说明 | 2581| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 2582| usage | [DeviceUsage](arkts-apis-audio-e.md#deviceusage12) | 是 | 设备种类。只支持排除输出设备。 | 2583 2584**返回值：** 2585 2586| 类型 | 说明 | 2587| --------------------- | --------------------------- | 2588| [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | 排除设备列表。 | 2589 2590**错误码：** 2591 2592以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 2593 2594| 错误码ID | 错误信息 | 2595| ------- | --------------------------------------------| 2596| 201 | Permission denied. Return by callback. | 2597| 202 | Not system App. | 2598| 6800101 | Parameter verification failed. | 2599 2600**示例：** 2601 2602```ts 2603import { audio } from '@kit.AudioKit'; 2604 2605let usage: audio.DeviceUsage.MEDIA_OUTPUT_DEVICES; 2606 2607async function getExcludedDevices(){ 2608 let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getExcludedDevices(usage); 2609 console.info(`device descriptor: ${desc}`); 2610} 2611``` 2612 2613## AudioRendererChangeInfo<sup>9+</sup> 2614 2615描述音频渲染器更改信息。 2616 2617**系统接口：** 该接口为系统接口。 2618 2619**系统能力：** SystemCapability.Multimedia.Audio.Renderer 2620 2621| 名称 | 类型 | 只读 | 可选 | 说明 | 2622| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- | 2623| clientUid | number | 是 | 否 | 音频渲染器客户端应用程序的Uid。 | 2624| rendererState | [AudioState](arkts-apis-audio-e.md#audiostate8) | 是 | 否 | 音频状态。| 2625 2626## AudioCapturerChangeInfo<sup>9+</sup> 2627 2628描述音频采集器更改信息。 2629 2630**系统接口：** 该接口为系统接口。 2631 2632**系统能力：** SystemCapability.Multimedia.Audio.Capturer 2633 2634| 名称 | 类型 | 只读 | 可选 | 说明 | 2635| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- | 2636| clientUid | number | 是 | 否 | 音频采集器客户端应用程序的Uid。 | 2637| capturerState | [AudioState](arkts-apis-audio-e.md#audiostate8) | 是 | 否 | 音频状态。| 2638 2639## AudioDeviceDescriptor 2640 2641描述音频设备。 2642 2643**系统接口：** 该接口为系统接口。 2644 2645| 名称 | 类型 | 只读 | 可选 | 说明 | 2646| ----------------------------- | -------------------------- | ---- | ---- | ---------- | 2647| networkId<sup>9+</sup> | string | 是 | 否 | 设备组网的ID。<br> **系统能力：** SystemCapability.Multimedia.Audio.Device| 2648| interruptGroupId<sup>9+</sup> | number | 是 | 否 | 设备所处的焦点组ID。<br> **系统能力：** SystemCapability.Multimedia.Audio.Device| 2649| volumeGroupId<sup>9+</sup> | number | 是 | 否 | 设备所处的音量组ID。<br> **系统能力：** SystemCapability.Multimedia.Audio.Device| 2650| dmDeviceType<sup>18+</sup> | number | 是 | 是 | 设备的子类型ID。<br> **系统能力：** SystemCapability.Multimedia.Audio.Core| 2651 2652## AudioRendererFilter<sup>9+</sup> 2653 2654过滤条件类。在调用selectOutputDeviceByFilter接口前，需要先创建AudioRendererFilter实例。 2655 2656**系统接口：** 该接口为系统接口。 2657 2658| 名称 | 类型 | 只读 | 可选 | 说明 | 2659| -------------| ---------------------------------------- | ---- |---| -------------- | 2660| uid | number | 否 | 是 | 表示应用ID。<br> **系统能力：** SystemCapability.Multimedia.Audio.Core| 2661| rendererInfo | [AudioRendererInfo](arkts-apis-audio-i.md#audiorendererinfo8) | 否 | 是 | 表示渲染器信息。<br> **系统能力：** SystemCapability.Multimedia.Audio.Renderer| 2662| rendererId | number | 否 | 是 | 音频流唯一id。<br> **系统能力：** SystemCapability.Multimedia.Audio.Renderer| 2663 2664**示例：** 2665 2666```ts 2667import { audio } from '@kit.AudioKit'; 2668 2669let outputAudioRendererFilter: audio.AudioRendererFilter = { 2670 uid : 20010041, 2671 rendererInfo : { 2672 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 2673 rendererFlags : 0 2674 }, 2675 rendererId : 0 2676}; 2677``` 2678 2679## AudioCapturerFilter<sup>18+</sup> 2680 2681过滤条件类。在调用selectOutputDeviceByFilter接口前，需要先创建AudioCapturerFilter实例。 2682 2683**系统接口：** 该接口为系统接口。 2684 2685| 名称 | 类型 | 只读 | 可选 | 说明 | 2686| -------------| ---------------------------------------- | ---- |---| -------------- | 2687| uid | number | 否 | 是 | 表示应用ID。<br> **系统能力：** SystemCapability.Multimedia.Audio.Core| 2688| capturerInfo | [AudioCapturerInfo](arkts-apis-audio-i.md#audiocapturerinfo8) | 否 | 是 | 表示采集器信息。<br> **系统能力：** SystemCapability.Multimedia.Audio.Capturer| 2689 2690**示例：** 2691 2692```ts 2693import { audio } from '@kit.AudioKit'; 2694 2695let inputAudioCapturerFilter: audio.AudioCapturerFilter = { 2696 uid : 20010041, 2697 capturerInfo : { 2698 source: audio.SourceType.SOURCE_TYPE_MIC, 2699 capturerFlags: 0 2700 } 2701}; 2702``` 2703 2704## AudioSpatialEnabledStateForDevice<sup>12+</sup> 2705 2706监听设备空间音频开关状态。 2707 2708**系统接口**：此接口为系统接口。 2709 2710**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2711 2712| 参数名 | 类型 | 只读 | 可选 | 说明 | 2713| ----------------------| ------------------------------------------------------------ | ---- |---| ------------------------- | 2714| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 否 | 否 | 指定设备的描述。 | 2715| enabled | boolean | 否 | 否 | 表示开启/关闭空间音频渲染或头动。true为开启，false为关闭。 | 2716 2717## AudioSpatializationManager<sup>11+</sup> 2718 2719空间音频管理。在使用AudioSpatializationManager的接口前，需要使用[getSpatializationManager](arkts-apis-audio-AudioManager.md#getspatializationmanager18)获取AudioSpatializationManager实例。 2720 2721### isSpatializationSupported<sup>11+</sup> 2722 2723isSpatializationSupported(): boolean 2724 2725获取系统是否支持空间音频，同步返回结果。 2726 2727**系统接口：** 该接口为系统接口。 2728 2729**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2730 2731**返回值：** 2732 2733| 类型 | 说明 | 2734| ---------------------- | ------------------------------------------------------------ | 2735| boolean | 返回系统是否支持空间音频，true为支持，false为不支持。 | 2736 2737**错误码：** 2738 2739以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2740 2741| 错误码ID | 错误信息 | 2742| ------- | --------------------------------------------| 2743| 202 | Not system App. | 2744 2745**示例：** 2746 2747```ts 2748import { audio } from '@kit.AudioKit'; 2749import { BusinessError } from '@kit.BasicServicesKit'; 2750try { 2751 let isSpatializationSupported: boolean = audioSpatializationManager.isSpatializationSupported(); 2752 console.info(`AudioSpatializationManager isSpatializationSupported: ${isSpatializationSupported}`); 2753} catch (err) { 2754 let error = err as BusinessError; 2755 console.error(`ERROR: ${error}`); 2756} 2757``` 2758 2759### isSpatializationSupportedForDevice<sup>11+</sup> 2760 2761isSpatializationSupportedForDevice(deviceDescriptor: AudioDeviceDescriptor): boolean 2762 2763获取指定设备是否支持空间音频，同步返回结果。 2764 2765**系统接口：** 该接口为系统接口。 2766 2767**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2768 2769**参数：** 2770 2771| 参数名 | 类型 | 必填 | 说明 | 2772| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 2773| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 是 | 指定设备的描述。 | 2774 2775**返回值：** 2776 2777| 类型 | 说明 | 2778| ---------------------- | ------------------------------------------------------------ | 2779| boolean | 返回指定设备是否支持空间音频，true为支持，false为不支持。 | 2780 2781**错误码：** 2782 2783以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 2784 2785| 错误码ID | 错误信息 | 2786| ------- | --------------------------------------------| 2787| 202 | Not system App. | 2788| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2789| 6800101 | Parameter verification failed. | 2790 2791**示例：** 2792 2793```ts 2794import { audio } from '@kit.AudioKit'; 2795import { BusinessError } from '@kit.BasicServicesKit'; 2796 2797let deviceDescriptor: audio.AudioDeviceDescriptor = { 2798 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2799 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2800 id : 1, 2801 name : "", 2802 address : "123", 2803 sampleRates : [44100], 2804 channelCounts : [2], 2805 channelMasks : [0], 2806 networkId : audio.LOCAL_NETWORK_ID, 2807 interruptGroupId : 1, 2808 volumeGroupId : 1, 2809 displayName : "" 2810}; 2811 2812try { 2813 let isSpatializationSupportedForDevice: boolean = audioSpatializationManager.isSpatializationSupportedForDevice(deviceDescriptor); 2814 console.info(`AudioSpatializationManager isSpatializationSupportedForDevice: ${isSpatializationSupportedForDevice}`); 2815} catch (err) { 2816 let error = err as BusinessError; 2817 console.error(`ERROR: ${error}`); 2818} 2819``` 2820 2821### isHeadTrackingSupported<sup>11+</sup> 2822 2823isHeadTrackingSupported(): boolean 2824 2825获取系统是否支持头动跟踪，同步返回结果。 2826 2827**系统接口：** 该接口为系统接口。 2828 2829**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2830 2831**返回值：** 2832 2833| 类型 | 说明 | 2834| ---------------------- | ------------------------------------------------------------ | 2835| boolean | 返回系统是否支持头动跟踪，true为支持，false为不支持。 | 2836 2837**错误码：** 2838 2839以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 2840 2841| 错误码ID | 错误信息 | 2842| ------- | --------------------------------------------| 2843| 202 | Not system App. | 2844 2845**示例：** 2846 2847```ts 2848import { audio } from '@kit.AudioKit'; 2849import { BusinessError } from '@kit.BasicServicesKit'; 2850 2851try { 2852 let isHeadTrackingSupported: boolean = audioSpatializationManager.isHeadTrackingSupported(); 2853 console.info(`AudioSpatializationManager isHeadTrackingSupported: ${isHeadTrackingSupported}`); 2854} catch (err) { 2855 let error = err as BusinessError; 2856 console.error(`ERROR: ${error}`); 2857} 2858``` 2859 2860### isHeadTrackingSupportedForDevice<sup>11+</sup> 2861 2862isHeadTrackingSupportedForDevice(deviceDescriptor: AudioDeviceDescriptor): boolean 2863 2864获取指定设备是否支持头动跟踪，同步返回结果。 2865 2866**系统接口：** 该接口为系统接口。 2867 2868**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2869 2870**参数：** 2871 2872| 参数名 | 类型 | 必填 | 说明 | 2873| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 2874| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 是 | 指定设备的描述。 | 2875 2876**返回值：** 2877 2878| 类型 | 说明 | 2879| ---------------------- | ------------------------------------------------------------ | 2880| boolean | 返回指定设备是否支持头动跟踪，true为支持，false为不支持。 | 2881 2882**错误码：** 2883 2884以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 2885 2886| 错误码ID | 错误信息 | 2887| ------- | --------------------------------------------| 2888| 202 | Not system App. | 2889| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2890| 6800101 | Parameter verification failed. | 2891 2892**示例：** 2893 2894```ts 2895import { audio } from '@kit.AudioKit'; 2896import { BusinessError } from '@kit.BasicServicesKit'; 2897 2898let deviceDescriptor: audio.AudioDeviceDescriptor = { 2899 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2900 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2901 id : 1, 2902 name : "", 2903 address : "123", 2904 sampleRates : [44100], 2905 channelCounts : [2], 2906 channelMasks : [0], 2907 networkId : audio.LOCAL_NETWORK_ID, 2908 interruptGroupId : 1, 2909 volumeGroupId : 1, 2910 displayName : "" 2911}; 2912 2913try { 2914 let isHeadTrackingSupportedForDevice: boolean = audioSpatializationManager.isHeadTrackingSupportedForDevice(deviceDescriptor); 2915 console.info(`AudioSpatializationManager isHeadTrackingSupportedForDevice: ${isHeadTrackingSupportedForDevice}`); 2916} catch (err) { 2917 let error = err as BusinessError; 2918 console.error(`ERROR: ${error}`); 2919} 2920``` 2921 2922### setSpatializationEnabled<sup>(deprecated)</sup> 2923 2924setSpatializationEnabled(enable: boolean, callback: AsyncCallback<void>): void 2925 2926根据输入指令，开启/关闭空间音频渲染效果。使用callback异步回调。 2927 2928> **说明：** 2929> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\<void>](#setspatializationenabled12)替代。 2930 2931**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2932 2933**系统接口：** 该接口为系统接口。 2934 2935**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2936 2937**参数：** 2938 2939| 参数名 | 类型 | 必填 | 说明 | 2940| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 2941| enable | boolean | 是 | 表示开启/关闭空间音频渲染。true为开启，false为关闭。 | 2942| callback | AsyncCallback<void> | 是 | 回调函数。当开启/关闭空间音频渲染效果成功，err为undefined，否则为错误对象。 | 2943 2944**错误码：** 2945 2946以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 2947 2948| 错误码ID | 错误信息 | 2949| ------- | --------------------------------------------| 2950| 201 | Permission denied. Return by callback. | 2951| 202 | Not system App. | 2952| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2953| 6800101 | Parameter verification failed. | 2954 2955**示例：** 2956```ts 2957import { audio } from '@kit.AudioKit'; 2958import { BusinessError } from '@kit.BasicServicesKit'; 2959 2960let enable: boolean = true; 2961 2962audioSpatializationManager.setSpatializationEnabled(enable, (err: BusinessError) => { 2963 if (err) { 2964 console.error(`Result ERROR: ${err}`); 2965 } else { 2966 console.info(`setSpatializationEnabled success`); 2967 } 2968}); 2969``` 2970 2971### setSpatializationEnabled<sup>(deprecated)</sup> 2972 2973setSpatializationEnabled(enable: boolean): Promise<void> 2974 2975根据输入指令，开启/关闭空间音频渲染效果。使用Promise异步回调。 2976 2977> **说明：** 2978> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\<void>](#setspatializationenabled12)替代。 2979 2980**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2981 2982**系统接口：** 该接口为系统接口。 2983 2984**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2985 2986**参数：** 2987 2988| 参数名 | 类型 | 必填 | 说明 | 2989| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 2990| enable | boolean | 是 | 表示开启/关闭空间音频渲染。true为开启，false为关闭。 | 2991 2992**返回值：** 2993 2994| 类型 | 说明 | 2995| --------------------- | --------------------------- | 2996| Promise<void> | Promise对象。无返回结果的Promise对象。 | 2997 2998**错误码：** 2999 3000以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3001 3002| 错误码ID | 错误信息 | 3003| ------- | --------------------------------------------| 3004| 201 | Permission denied. Return by promise. | 3005| 202 | Not system App. | 3006| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3007 3008**示例：** 3009 3010```ts 3011import { audio } from '@kit.AudioKit'; 3012import { BusinessError } from '@kit.BasicServicesKit'; 3013 3014let enable: boolean = true; 3015 3016audioSpatializationManager.setSpatializationEnabled(enable).then(() => { 3017 console.info(`setSpatializationEnabled success`); 3018}).catch((err: BusinessError) => { 3019 console.error(`Result ERROR: ${err}`); 3020}); 3021``` 3022### setSpatializationEnabled<sup>12+</sup> 3023 3024setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise<void> 3025 3026根据输入指令，开启/关闭指定设备的空间音频渲染效果。使用Promise异步回调。 3027 3028**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 3029 3030**系统接口：** 该接口为系统接口。 3031 3032**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3033 3034**参数：** 3035 3036| 参数名 | 类型 | 必填 | 说明 | 3037| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 3038| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 是 | 指定设备的描述。 | 3039| enabled | boolean | 是 | 表示开启/关闭空间音频渲染。true为开启，false为关闭。 | 3040 3041**返回值：** 3042 3043| 类型 | 说明 | 3044| --------------------- | --------------------------- | 3045| Promise<void> | Promise对象。无返回结果的Promise对象。 | 3046 3047**错误码：** 3048 3049以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3050 3051| 错误码ID | 错误信息 | 3052| ------- | --------------------------------------------| 3053| 201 | Permission denied. Return by promise. | 3054| 202 | Not system App. | 3055| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3056| 6800101 | Parameter verification failed. | 3057 3058 3059**示例：** 3060 3061```ts 3062import { audio } from '@kit.AudioKit'; 3063import { BusinessError } from '@kit.BasicServicesKit'; 3064 3065let deviceDescriptor: audio.AudioDeviceDescriptor = { 3066 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 3067 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 3068 id : 1, 3069 name : "", 3070 address : "123", 3071 sampleRates : [44100], 3072 channelCounts : [2], 3073 channelMasks : [0], 3074 networkId : audio.LOCAL_NETWORK_ID, 3075 interruptGroupId : 1, 3076 volumeGroupId : 1, 3077 displayName : "" 3078}; 3079let enabled: boolean = true; 3080 3081audioSpatializationManager.setSpatializationEnabled(deviceDescriptor, enabled).then(() => { 3082 console.info(`setSpatializationEnabled success`); 3083}).catch((err: BusinessError) => { 3084 console.error(`Result ERROR: ${err}`); 3085}); 3086``` 3087 3088### isSpatializationEnabled<sup>(deprecated)</sup> 3089 3090isSpatializationEnabled(): boolean 3091 3092获取空间音频渲染是否开启，同步返回结果。 3093 3094> **说明：** 3095> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[isSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean](#isspatializationenabled12)替代。 3096 3097**系统接口：** 该接口为系统接口。 3098 3099**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3100 3101**返回值：** 3102 3103| 类型 | 说明 | 3104| ---------------------- | ------------------------------------------------------------ | 3105| boolean | 返回空间音频渲染是否开启，true为开启，false为未开启。 | 3106 3107**错误码：** 3108 3109以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3110 3111| 错误码ID | 错误信息 | 3112| ------- | --------------------------------------------| 3113| 202 | Not system App. | 3114 3115**示例：** 3116 3117```ts 3118import { audio } from '@kit.AudioKit'; 3119import { BusinessError } from '@kit.BasicServicesKit'; 3120 3121try { 3122 let isSpatializationEnabled: boolean = audioSpatializationManager.isSpatializationEnabled(); 3123 console.info(`AudioSpatializationManager isSpatializationEnabled: ${isSpatializationEnabled}`); 3124} catch (err) { 3125 let error = err as BusinessError; 3126 console.error(`ERROR: ${error}`); 3127} 3128``` 3129 3130### isSpatializationEnabled<sup>12+</sup> 3131 3132isSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean 3133 3134获取指定设备的空间音频渲染是否开启，同步返回结果。 3135 3136**系统接口：** 该接口为系统接口。 3137 3138**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3139 3140**参数：** 3141 3142| 参数名 | 类型 | 必填 | 说明 | 3143| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 3144| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 是 | 指定设备的描述。 | 3145 3146**返回值：** 3147 3148| 类型 | 说明 | 3149| ---------------------- | ------------------------------------------------------------ | 3150| boolean | 返回指定设备的空间音频渲染是否开启，true为开启，false为未开启。 | 3151 3152**错误码：** 3153 3154以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3155 3156| 错误码ID | 错误信息 | 3157| ------- | --------------------------------------------| 3158| 202 | Not system App. | 3159| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3160| 6800101 | Parameter verification failed. | 3161 3162**示例：** 3163 3164```ts 3165import { audio } from '@kit.AudioKit'; 3166import { BusinessError } from '@kit.BasicServicesKit'; 3167 3168let deviceDescriptor: audio.AudioDeviceDescriptor = { 3169 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 3170 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 3171 id : 1, 3172 name : "", 3173 address : "123", 3174 sampleRates : [44100], 3175 channelCounts : [2], 3176 channelMasks : [0], 3177 networkId : audio.LOCAL_NETWORK_ID, 3178 interruptGroupId : 1, 3179 volumeGroupId : 1, 3180 displayName : "" 3181}; 3182 3183try { 3184 let isSpatializationEnabled: boolean = audioSpatializationManager.isSpatializationEnabled(deviceDescriptor); 3185 console.info(`AudioSpatializationManager isSpatializationEnabled: ${isSpatializationEnabled}`); 3186} catch (err) { 3187 let error = err as BusinessError; 3188 console.error(`ERROR: ${error}`); 3189} 3190``` 3191 3192### on('spatializationEnabledChange')<sup>(deprecated)</sup> 3193 3194on(type: 'spatializationEnabledChange', callback: Callback<boolean\>): void 3195 3196监听空间音频渲染开关状态变化事件（当空间音频渲染开关状态发生变化时触发）。使用callback异步回调。 3197 3198> **说明：** 3199> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[on(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void](#onspatializationenabledchangeforanydevice12)替代。 3200 3201**系统接口：** 该接口为系统接口。 3202 3203**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3204 3205**参数：** 3206 3207| 参数名 | 类型 | 必填 | 说明 | 3208| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------| 3209| type | string | 是 | 事件回调类型，支持的事件为'spatializationEnabledChange'，当空间音频渲染开关状态发生变化时，触发该事件。 | 3210| callback | Callback<boolean\> | 是 | 回调函数。返回true表示音频渲染已打开；返回false表示音频渲染已关闭。 | 3211 3212**错误码：** 3213 3214以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3215 3216| 错误码ID | 错误信息 | 3217| ------- | --------------------------------------------| 3218| 202 | Not system App. | 3219| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3220| 6800101 | Parameter verification failed. | 3221 3222**示例：** 3223 3224```ts 3225import { audio } from '@kit.AudioKit'; 3226 3227audioSpatializationManager.on('spatializationEnabledChange', (isSpatializationEnabled: boolean) => { 3228 console.info(`isSpatializationEnabled: ${isSpatializationEnabled}`); 3229}); 3230``` 3231 3232### on('spatializationEnabledChangeForAnyDevice')<sup>12+</sup> 3233 3234on(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void 3235 3236监听空间音频渲染开关状态变化事件（当空间音频渲染开关状态发生变化时触发）。使用callback异步回调。 3237 3238**系统接口：** 该接口为系统接口。 3239 3240**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3241 3242**参数：** 3243 3244| 参数名 | 类型 | 必填 | 说明 | 3245| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------| 3246| type | string | 是 | 事件回调类型，支持的事件为'spatializationEnabledChangeForAnyDevice'，当空间音频渲染开关状态发生变化时，触发该事件。 | 3247| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | 是 | 回调函数，返回设备信息和空间音频渲染开关状态。 | 3248 3249**错误码：** 3250 3251以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3252 3253| 错误码ID | 错误信息 | 3254| ------- | --------------------------------------------| 3255| 202 | Not system App. | 3256| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3257| 6800101 | Parameter verification failed. | 3258 3259**示例：** 3260 3261```ts 3262import { audio } from '@kit.AudioKit'; 3263 3264audioSpatializationManager.on('spatializationEnabledChangeForAnyDevice', (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 3265 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 3266 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 3267}); 3268``` 3269 3270### off('spatializationEnabledChange')<sup>(deprecated)</sup> 3271 3272off(type: 'spatializationEnabledChange', callback?: Callback<boolean\>): void 3273 3274取消监听空间音频渲染开关状态变化事件。使用callback异步回调。 3275 3276> **说明：** 3277> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[off(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void](#offspatializationenabledchangeforanydevice12)替代。 3278 3279**系统接口：** 该接口为系统接口。 3280 3281**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3282 3283**参数：** 3284 3285| 参数名 | 类型 | 必填 | 说明 | 3286| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 3287| type | string | 是 | 事件回调类型，支持的事件为'spatializationEnabledChange'，当取消监听空间音频渲染开关状态变化事件时，触发该事件。 | 3288| callback | Callback<boolean\> | 否 | 回调函数。返回true表示音频渲染已打开；返回false表示音频渲染已关闭。 | 3289 3290**错误码：** 3291 3292以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3293 3294| 错误码ID | 错误信息 | 3295| ------- | --------------------------------------------| 3296| 202 | Not system App. | 3297| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3298| 6800101 | Parameter verification failed. | 3299 3300**示例：** 3301 3302```ts 3303// 取消该事件的所有监听。 3304audioSpatializationManager.off('spatializationEnabledChange'); 3305 3306// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 3307let spatializationEnabledChangeCallback = (isSpatializationEnabled: boolean) => { 3308 console.info(`isSpatializationEnabled: ${isSpatializationEnabled}`); 3309}; 3310 3311audioSpatializationManager.on('spatializationEnabledChange', spatializationEnabledChangeCallback); 3312 3313audioSpatializationManager.off('spatializationEnabledChange', spatializationEnabledChangeCallback); 3314``` 3315 3316### off('spatializationEnabledChangeForAnyDevice')<sup>12+</sup> 3317 3318off(type: 'spatializationEnabledChangeForAnyDevice', callback?: Callback<AudioSpatialEnabledStateForDevice\>): void 3319 3320取消监听空间音频渲染开关状态变化事件。使用callback异步回调。 3321 3322**系统接口：** 该接口为系统接口。 3323 3324**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3325 3326**参数：** 3327 3328| 参数名 | 类型 | 必填 | 说明 | 3329| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------| 3330| type | string | 是 | 事件回调类型，支持的事件为'spatializationEnabledChangeForAnyDevice'，当取消监听空间音频渲染开关状态变化事件时，触发该事件。 | 3331| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | 是 | 回调函数，返回设备信息和空间音频渲染开关状态。 | 3332 3333**错误码：** 3334 3335以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3336 3337| 错误码ID | 错误信息 | 3338| ------- | --------------------------------------------| 3339| 202 | Not system App. | 3340| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3341| 6800101 | Parameter verification failed. | 3342 3343**示例：** 3344 3345```ts 3346import { audio } from '@kit.AudioKit'; 3347 3348// 取消该事件的所有监听。 3349audioSpatializationManager.off('spatializationEnabledChangeForAnyDevice'); 3350 3351// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 3352let spatializationEnabledChangeForAnyDeviceCallback = (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 3353 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 3354 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 3355}; 3356 3357audioSpatializationManager.on('spatializationEnabledChangeForAnyDevice', spatializationEnabledChangeForAnyDeviceCallback); 3358 3359audioSpatializationManager.off('spatializationEnabledChangeForAnyDevice', spatializationEnabledChangeForAnyDeviceCallback); 3360``` 3361 3362### setHeadTrackingEnabled<sup>(deprecated)</sup> 3363 3364setHeadTrackingEnabled(enable: boolean, callback: AsyncCallback<void>): void 3365 3366根据输入指令，开启/关闭头动跟踪效果。使用callback异步回调。 3367 3368> **说明：** 3369> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[setHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\<void>](#setheadtrackingenabled12)替代。 3370 3371**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 3372 3373**系统接口：** 该接口为系统接口。 3374 3375**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3376 3377**参数：** 3378 3379| 参数名 | 类型 | 必填 | 说明 | 3380| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 3381| enable | boolean | 是 | 表示开启/关闭头动跟踪。true为开启，false为关闭。 | 3382| callback | AsyncCallback<void> | 是 | 回调函数。当开启/关闭头动跟踪效果成功，err为undefined，否则为错误对象。 | 3383 3384**错误码：** 3385 3386以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3387 3388| 错误码ID | 错误信息 | 3389| ------- | --------------------------------------------| 3390| 201 | Permission denied. Return by callback. | 3391| 202 | Not system App. | 3392| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3393| 6800101 | Parameter verification failed. | 3394 3395**示例：** 3396```ts 3397import { audio } from '@kit.AudioKit'; 3398import { BusinessError } from '@kit.BasicServicesKit'; 3399 3400let enable: boolean = true; 3401 3402audioSpatializationManager.setHeadTrackingEnabled(enable, (err: BusinessError) => { 3403 if (err) { 3404 console.error(`Result ERROR: ${err}`); 3405 } else { 3406 console.info(`setHeadTrackingEnabled success`); 3407 } 3408}); 3409``` 3410 3411### setHeadTrackingEnabled<sup>(deprecated)</sup> 3412 3413setHeadTrackingEnabled(enable: boolean): Promise<void> 3414 3415根据输入指令，开启/关闭头动跟踪效果。使用Promise异步回调。 3416 3417> **说明：** 3418> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[setHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\<void>](#setheadtrackingenabled12)替代。 3419 3420**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 3421 3422**系统接口：** 该接口为系统接口。 3423 3424**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3425 3426**参数：** 3427 3428| 参数名 | 类型 | 必填 | 说明 | 3429| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 3430| enable | boolean | 是 | 表示开启/关闭头动跟踪。true为开启，false为关闭。 | 3431 3432**返回值：** 3433 3434| 类型 | 说明 | 3435| --------------------- | --------------------------- | 3436| Promise<void> | Promise对象。无返回结果的Promise对象。 | 3437 3438**错误码：** 3439 3440以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3441 3442| 错误码ID | 错误信息 | 3443| ------- | --------------------------------------------| 3444| 201 | Permission denied. Return by promise. | 3445| 202 | Not system App. | 3446| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3447 3448**示例：** 3449 3450```ts 3451import { audio } from '@kit.AudioKit'; 3452import { BusinessError } from '@kit.BasicServicesKit'; 3453 3454let enable: boolean = true; 3455 3456audioSpatializationManager.setHeadTrackingEnabled(enable).then(() => { 3457 console.info(`setHeadTrackingEnabled success`); 3458}).catch((err: BusinessError) => { 3459 console.error(`Result ERROR: ${err}`); 3460}); 3461``` 3462 3463### setHeadTrackingEnabled<sup>12+</sup> 3464 3465setHeadTrackingEnabled(enable: boolean): Promise<void> 3466 3467根据输入指令，开启/关闭指定设备的头动跟踪效果。使用Promise异步回调。 3468 3469**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 3470 3471**系统接口：** 该接口为系统接口。 3472 3473**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3474 3475**参数：** 3476 3477| 参数名 | 类型 | 必填 | 说明 | 3478| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 3479| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 是 | 指定设备的描述。 | 3480| enable | boolean | 是 | 表示开启/关闭头动跟踪。true为开启，false为关闭。 | 3481 3482**返回值：** 3483 3484| 类型 | 说明 | 3485| --------------------- | --------------------------- | 3486| Promise<void> | Promise对象。无返回结果的Promise对象。 | 3487 3488**错误码：** 3489 3490以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3491 3492| 错误码ID | 错误信息 | 3493| ------- | --------------------------------------------| 3494| 201 | Permission denied. Return by promise. | 3495| 202 | Not system App. | 3496| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3497| 6800101 | Parameter verification failed. | 3498 3499**示例：** 3500 3501```ts 3502import { audio } from '@kit.AudioKit'; 3503import { BusinessError } from '@kit.BasicServicesKit'; 3504 3505let deviceDescriptor: audio.AudioDeviceDescriptor = { 3506 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 3507 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 3508 id : 1, 3509 name : "", 3510 address : "123", 3511 sampleRates : [44100], 3512 channelCounts : [2], 3513 channelMasks : [0], 3514 networkId : audio.LOCAL_NETWORK_ID, 3515 interruptGroupId : 1, 3516 volumeGroupId : 1, 3517 displayName : "" 3518}; 3519let enable: boolean = true; 3520 3521audioSpatializationManager.setHeadTrackingEnabled(deviceDescriptor, enable).then(() => { 3522 console.info(`setHeadTrackingEnabled success`); 3523}).catch((err: BusinessError) => { 3524 console.error(`Result ERROR: ${err}`); 3525}); 3526``` 3527 3528### isHeadTrackingEnabled<sup>(deprecated)</sup> 3529 3530isHeadTrackingEnabled(): boolean 3531 3532获取头动跟踪是否开启，同步返回结果。 3533 3534> **说明：** 3535> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[isHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean](#isheadtrackingenabled12)替代。 3536 3537**系统接口：** 该接口为系统接口。 3538 3539**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3540 3541**返回值：** 3542 3543| 类型 | 说明 | 3544| ---------------------- | ------------------------------------------------------------ | 3545| boolean | 返回头动跟踪是否开启，true为开启，false为未开启。 | 3546 3547**错误码：** 3548 3549以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3550 3551| 错误码ID | 错误信息 | 3552| ------- | --------------------------------------------| 3553| 202 | Not system App. | 3554 3555**示例：** 3556 3557```ts 3558import { audio } from '@kit.AudioKit'; 3559import { BusinessError } from '@kit.BasicServicesKit'; 3560 3561try { 3562 let isHeadTrackingEnabled: boolean = audioSpatializationManager.isHeadTrackingEnabled(); 3563 console.info(`AudioSpatializationManager isHeadTrackingEnabled: ${isHeadTrackingEnabled}`); 3564} catch (err) { 3565 let error = err as BusinessError; 3566 console.error(`ERROR: ${error}`); 3567} 3568``` 3569 3570### isHeadTrackingEnabled<sup>12+</sup> 3571 3572isHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean 3573 3574获取指定设备的头动跟踪是否开启，同步返回结果。 3575 3576**系统接口：** 该接口为系统接口。 3577 3578**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3579 3580**参数：** 3581 3582| 参数名 | 类型 | 必填 | 说明 | 3583| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 3584| deviceDescriptor | [AudioDeviceDescriptor](arkts-apis-audio-i.md#audiodevicedescriptor) | 是 | 指定设备的描述。 | 3585 3586**返回值：** 3587 3588| 类型 | 说明 | 3589| ---------------------- | ------------------------------------------------------------ | 3590| boolean | 返回指定设备的头动跟踪是否开启，true为开启，false为未开启。 | 3591 3592**错误码：** 3593 3594以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3595 3596| 错误码ID | 错误信息 | 3597| ------- | --------------------------------------------| 3598| 202 | Not system App. | 3599| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3600| 6800101 | Parameter verification failed. | 3601 3602**示例：** 3603 3604```ts 3605import { audio } from '@kit.AudioKit'; 3606import { BusinessError } from '@kit.BasicServicesKit'; 3607 3608let deviceDescriptor: audio.AudioDeviceDescriptor = { 3609 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 3610 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 3611 id : 1, 3612 name : "", 3613 address : "123", 3614 sampleRates : [44100], 3615 channelCounts : [2], 3616 channelMasks : [0], 3617 networkId : audio.LOCAL_NETWORK_ID, 3618 interruptGroupId : 1, 3619 volumeGroupId : 1, 3620 displayName : "" 3621}; 3622 3623try { 3624 let isHeadTrackingEnabled: boolean = audioSpatializationManager.isHeadTrackingEnabled(deviceDescriptor); 3625 console.info(`AudioSpatializationManager isHeadTrackingEnabled: ${isHeadTrackingEnabled}`); 3626} catch (err) { 3627 let error = err as BusinessError; 3628 console.error(`ERROR: ${error}`); 3629} 3630``` 3631 3632### on('headTrackingEnabledChange')<sup>(deprecated)</sup> 3633 3634on(type: 'headTrackingEnabledChange', callback: Callback<boolean\>): void 3635 3636监听头动跟踪开关状态变化事件（当动跟踪开关状态发生变化时触发）。使用callback异步回调。 3637 3638> **说明：** 3639> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[on(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void](#onheadtrackingenabledchangeforanydevice12)替代。 3640 3641**系统接口：** 该接口为系统接口。 3642 3643**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3644 3645**参数：** 3646 3647| 参数名 | 类型 | 必填 | 说明 | 3648| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 3649| type | string | 是 | 事件回调类型，支持的事件为'headTrackingEnabledChange'，当动跟踪开关状态发生变化时，触发该事件。 | 3650| callback | Callback<boolean\> | 是 | 回调函数。返回true表示头动跟踪已打开；返回false表示头动跟踪已关闭。 | 3651 3652**错误码：** 3653 3654以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3655 3656| 错误码ID | 错误信息 | 3657| ------- | --------------------------------------------| 3658| 202 | Not system App. | 3659| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3660| 6800101 | Parameter verification failed. | 3661 3662**示例：** 3663 3664```ts 3665import { audio } from '@kit.AudioKit'; 3666 3667audioSpatializationManager.on('headTrackingEnabledChange', (isHeadTrackingEnabled: boolean) => { 3668 console.info(`isHeadTrackingEnabled: ${isHeadTrackingEnabled}`); 3669}); 3670``` 3671 3672### on('headTrackingEnabledChangeForAnyDevice')<sup>12+</sup> 3673 3674on(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void 3675 3676监听头动跟踪开关状态变化事件（当动跟踪开关状态发生变化时触发）。使用callback异步回调。 3677 3678**系统接口：** 该接口为系统接口。 3679 3680**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3681 3682**参数：** 3683 3684| 参数名 | 类型 | 必填 | 说明 | 3685| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 3686| type | string | 是 | 事件回调类型，支持的事件为'headTrackingEnabledChangeForAnyDevice'，当动跟踪开关状态发生变化时，触发该事件。 | 3687| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | 是 | 回调函数。返回true表示头动跟踪已打开；返回false表示头动跟踪已关闭。 | 3688 3689**错误码：** 3690 3691以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3692 3693| 错误码ID | 错误信息 | 3694| ------- | --------------------------------------------| 3695| 202 | Not system App. | 3696| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3697| 6800101 | Parameter verification failed. | 3698 3699**示例：** 3700 3701```ts 3702import { audio } from '@kit.AudioKit'; 3703 3704audioSpatializationManager.on('headTrackingEnabledChangeForAnyDevice', (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 3705 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 3706 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 3707}); 3708``` 3709 3710### off('headTrackingEnabledChange')<sup>(deprecated)</sup> 3711 3712off(type: 'headTrackingEnabledChange', callback?: Callback<boolean\>): void 3713 3714取消监听头动跟踪开关状态变化事件。使用callback异步回调。 3715 3716> **说明：** 3717> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[off(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void](#offheadtrackingenabledchangeforanydevice12)替代。 3718 3719**系统接口：** 该接口为系统接口。 3720 3721**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3722 3723**参数：** 3724 3725| 参数名 | 类型 | 必填 | 说明 | 3726| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 3727| type | string | 是 | 事件回调类型，支持的事件为'headTrackingEnabledChange'，当取消监听头动跟踪开关状态变化事件时，触发该事件。 | 3728| callback | Callback<boolean\> | 否 | 回调函数。返回true表示头动跟踪已打开；返回false表示头动跟踪已关闭。 | 3729 3730**错误码：** 3731 3732以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3733 3734| 错误码ID | 错误信息 | 3735| ------- | --------------------------------------------| 3736| 202 | Not system App. | 3737| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3738| 6800101 | Parameter verification failed. | 3739 3740**示例：** 3741 3742```ts 3743import { audio } from '@kit.AudioKit'; 3744 3745// 取消该事件的所有监听。 3746audioSpatializationManager.off('headTrackingEnabledChange'); 3747 3748// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 3749let headTrackingEnabledChangeCallback = (isHeadTrackingEnabled: boolean) => { 3750 console.info(`isHeadTrackingEnabled: ${isHeadTrackingEnabled}`); 3751}; 3752 3753audioSpatializationManager.on('headTrackingEnabledChange', headTrackingEnabledChangeCallback); 3754 3755audioSpatializationManager.off('headTrackingEnabledChange', headTrackingEnabledChangeCallback); 3756``` 3757 3758### off('headTrackingEnabledChangeForAnyDevice')<sup>12+</sup> 3759 3760off(type: 'headTrackingEnabledChangeForAnyDevice', callback?: Callback<AudioSpatialEnabledStateForDevice\>): void 3761 3762取消监听头动跟踪开关状态变化事件。使用callback异步回调。 3763 3764**系统接口：** 该接口为系统接口。 3765 3766**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3767 3768**参数：** 3769 3770| 参数名 | 类型 | 必填 | 说明 | 3771| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 3772| type | string | 是 | 事件回调类型，支持的事件为'headTrackingEnabledChangeForAnyDevice'，当取消监听头动跟踪开关状态变化事件时，触发该事件。 | 3773| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | 是 | 回调函数。返回true表示头动跟踪已打开；返回false表示头动跟踪已关闭。 | 3774 3775**错误码：** 3776 3777以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3778 3779| 错误码ID | 错误信息 | 3780| ------- | --------------------------------------------| 3781| 202 | Not system App. | 3782| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3783| 6800101 | Parameter verification failed. | 3784 3785**示例：** 3786 3787```ts 3788import { audio } from '@kit.AudioKit'; 3789 3790// 取消该事件的所有监听。 3791audioSpatializationManager.off('headTrackingEnabledChangeForAnyDevice'); 3792 3793// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 3794let headTrackingEnabledChangeForAnyDeviceCallback = (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 3795 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 3796 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 3797}; 3798 3799audioSpatializationManager.on('headTrackingEnabledChangeForAnyDevice', headTrackingEnabledChangeForAnyDeviceCallback); 3800 3801audioSpatializationManager.off('headTrackingEnabledChangeForAnyDevice', headTrackingEnabledChangeForAnyDeviceCallback); 3802``` 3803 3804### updateSpatialDeviceState<sup>11+</sup> 3805 3806updateSpatialDeviceState(spatialDeviceState: AudioSpatialDeviceState): void 3807 3808更新空间化设备状态，同步返回结果。 3809 3810**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 3811 3812**系统接口：** 该接口为系统接口。 3813 3814**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3815 3816**参数：** 3817 3818| 参数名 | 类型 | 必填 | 说明 | 3819| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 3820| spatialDeviceState | [AudioSpatialDeviceState](#audiospatialdevicestate11) | 是 | 需要更新的空间化设备状态。 | 3821 3822**错误码：** 3823 3824以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3825 3826| 错误码ID | 错误信息 | 3827| ------- | --------------------------------------------| 3828| 201 | Permission denied. | 3829| 202 | Not system App. | 3830| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3831| 6800101 | Parameter verification failed. | 3832 3833**示例：** 3834 3835```ts 3836import { audio } from '@kit.AudioKit'; 3837import { BusinessError } from '@kit.BasicServicesKit'; 3838 3839let spatialDeviceState: audio.AudioSpatialDeviceState = { 3840 address: "123", 3841 isSpatializationSupported: true, 3842 isHeadTrackingSupported: true, 3843 spatialDeviceType: audio.AudioSpatialDeviceType.SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE 3844}; 3845 3846try { 3847 audioSpatializationManager.updateSpatialDeviceState(spatialDeviceState); 3848 console.info(`AudioSpatializationManager updateSpatialDeviceState success`); 3849} catch (err) { 3850 let error = err as BusinessError; 3851 console.error(`ERROR: ${error}`); 3852} 3853``` 3854 3855### setSpatializationSceneType<sup>12+</sup> 3856 3857setSpatializationSceneType(spatializationSceneType: AudioSpatializationSceneType): void 3858 3859设置空间音频渲染场景类型，同步返回结果。 3860 3861**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 3862 3863**系统接口：** 该接口为系统接口。 3864 3865**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3866 3867**参数：** 3868 3869| 参数名 | 类型 | 必填 | 说明 | 3870| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 3871| spatializationSceneType | [AudioSpatializationSceneType](#audiospatializationscenetype12) | 是 | 需要设置的空间音频渲染场景类型。 | 3872 3873**错误码：** 3874 3875以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 3876 3877| 错误码ID | 错误信息 | 3878| ------- | --------------------------------------------| 3879| 201 | Permission denied. | 3880| 202 | Not system App. | 3881| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3882| 6800101 | Parameter verification failed. | 3883 3884**示例：** 3885 3886```ts 3887import { audio } from '@kit.AudioKit'; 3888import { BusinessError } from '@kit.BasicServicesKit'; 3889 3890try { 3891 audioSpatializationManager.setSpatializationSceneType(audio.AudioSpatializationSceneType.DEFAULT); 3892 console.info(`AudioSpatializationManager setSpatializationSceneType success`); 3893} catch (err) { 3894 let error = err as BusinessError; 3895 console.error(`ERROR: ${error}`); 3896} 3897``` 3898 3899### getSpatializationSceneType<sup>12+</sup> 3900 3901getSpatializationSceneType(): AudioSpatializationSceneType 3902 3903查询当前空间音频渲染场景类型，同步返回结果。 3904 3905**系统接口：** 该接口为系统接口。 3906 3907**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3908 3909**返回值：** 3910 3911| 类型 | 说明 | 3912| ---------------------- | ------------------------------------------------------------ | 3913| [AudioSpatializationSceneType](#audiospatializationscenetype12) | 返回当前空间音频渲染场景类型。 | 3914 3915**错误码：** 3916 3917以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 3918 3919| 错误码ID | 错误信息 | 3920| ------- | --------------------------------------------| 3921| 202 | Not system App. | 3922 3923**示例：** 3924 3925```ts 3926import { audio } from '@kit.AudioKit'; 3927import { BusinessError } from '@kit.BasicServicesKit'; 3928 3929try { 3930 let spatializationSceneType: audio.AudioSpatializationSceneType = audioSpatializationManager.getSpatializationSceneType(); 3931 console.info(`AudioSpatializationManager spatializationSceneType: ${spatializationSceneType}`); 3932} catch (err) { 3933 let error = err as BusinessError; 3934 console.error(`ERROR: ${error}`); 3935} 3936``` 3937 3938## AudioSpatialDeviceState<sup>11+</sup> 3939 3940空间化设备状态。 3941 3942**系统接口：** 该接口为系统接口。 3943 3944**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3945 3946| 名称 | 类型 | 只读 | 可选 | 说明 | 3947| ----------------------------- | -------------------------- | ---- | ---- | ---------- | 3948| address | string | 否 | 否 | 空间化设备地址。| 3949| isSpatializationSupported | boolean | 否 | 否 | 空间化设备是否支持空间音频渲染。true表示支持，false表示不支持。| 3950| isHeadTrackingSupported | boolean | 否 | 否 | 空间化设备是否支持头动跟踪。true表示支持，false表示不支持。| 3951| spatialDeviceType | [AudioSpatialDeviceType](#audiospatialdevicetype11) | 否 | 否 | 空间化设备类型。| 3952 3953**示例：** 3954 3955```ts 3956import { audio } from '@kit.AudioKit'; 3957 3958let spatialDeviceState: audio.AudioSpatialDeviceState = { 3959 address: "123", 3960 isSpatializationSupported: true, 3961 isHeadTrackingSupported: true, 3962 spatialDeviceType: audio.AudioSpatialDeviceType.SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE 3963}; 3964``` 3965 3966## AudioSpatialDeviceType<sup>11+</sup> 3967 3968枚举，空间化设备类型。 3969 3970**系统接口：** 该接口为系统接口。 3971 3972**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3973 3974| 名称 | 值 | 说明 | 3975| ---------------------------------- | ------ | ------------------------- | 3976| SPATIAL_DEVICE_TYPE_NONE | 0 | 无空间化设备类型。 | 3977| SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE | 1 | 入耳式耳机。 | 3978| SPATIAL_DEVICE_TYPE_HALF_IN_EAR_HEADPHONE | 2 | 半入耳式耳机。 | 3979| SPATIAL_DEVICE_TYPE_OVER_EAR_HEADPHONE | 3 | 头戴式耳机。 | 3980| SPATIAL_DEVICE_TYPE_GLASSES | 4 | 眼镜式耳机。 | 3981| SPATIAL_DEVICE_TYPE_OTHERS | 5 | 其他空间化设备类型。| 3982 3983## AudioSpatializationSceneType<sup>12+</sup> 3984 3985枚举，空间音频渲染场景类型。 3986 3987**系统接口：** 该接口为系统接口。 3988 3989**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 3990 3991| 名称 | 值 | 说明 | 3992| ---------------------------------- | ------ | ------------------------- | 3993| DEFAULT | 0 | 空间音频默认渲染场景。 | 3994| MUSIC | 1 | 空间音频音乐渲染场景。 | 3995| MOVIE | 2 | 空间音频电影渲染场景。 | 3996| AUDIOBOOK | 3 | 空间音频有声读物渲染场景。 | 3997 3998## ToneType<sup>9+</sup> 3999 4000枚举，播放器的音调类型。 4001 4002**系统接口：** 该接口为系统接口。 4003 4004**系统能力：** SystemCapability.Multimedia.Audio.Tone 4005 4006| 名称 | 值 | 说明 | 4007| :------------------------------------------------ | :----- | :----------------------------| 4008| TONE_TYPE_DIAL_0 | 0 | 键0的DTMF音。 | 4009| TONE_TYPE_DIAL_1 | 1 | 键1的DTMF音。 | 4010| TONE_TYPE_DIAL_2 | 2 | 键2的DTMF音。 | 4011| TONE_TYPE_DIAL_3 | 3 | 键3的DTMF音。 | 4012| TONE_TYPE_DIAL_4 | 4 | 键4的DTMF音。 | 4013| TONE_TYPE_DIAL_5 | 5 | 键5的DTMF音。 | 4014| TONE_TYPE_DIAL_6 | 6 | 键6的DTMF音。 | 4015| TONE_TYPE_DIAL_7 | 7 | 键7的DTMF音。 | 4016| TONE_TYPE_DIAL_8 | 8 | 键8的DTMF音。 | 4017| TONE_TYPE_DIAL_9 | 9 | 键9的DTMF音。 | 4018| TONE_TYPE_DIAL_S | 10 | 键*的DTMF音。 | 4019| TONE_TYPE_DIAL_P | 11 | 键#的DTMF音。 | 4020| TONE_TYPE_DIAL_A | 12 | 键A的DTMF音。 | 4021| TONE_TYPE_DIAL_B | 13 | 键B的DTMF音。 | 4022| TONE_TYPE_DIAL_C | 14 | 键C的DTMF音。 | 4023| TONE_TYPE_DIAL_D | 15 | 键D的DTMF音。 | 4024| TONE_TYPE_COMMON_SUPERVISORY_DIAL | 100 | 呼叫监管音调，拨号音。 | 4025| TONE_TYPE_COMMON_SUPERVISORY_BUSY | 101 | 呼叫监管音调，忙。 | 4026| TONE_TYPE_COMMON_SUPERVISORY_CONGESTION | 102 | 呼叫监管音调，拥塞。 | 4027| TONE_TYPE_COMMON_SUPERVISORY_RADIO_ACK | 103 | 呼叫监管音调，无线电 ACK。 | 4028| TONE_TYPE_COMMON_SUPERVISORY_RADIO_NOT_AVAILABLE | 104 | 呼叫监管音调，无线电不可用。 | 4029| TONE_TYPE_COMMON_SUPERVISORY_CALL_WAITING | 106 | 呼叫监管音调，呼叫等待。 | 4030| TONE_TYPE_COMMON_SUPERVISORY_RINGTONE | 107 | 呼叫监管音调，铃声。 | 4031| TONE_TYPE_COMMON_SUPERVISORY_CALL_HOLDING<sup>18+</sup> | 108 | 呼叫保持音调。 | 4032| TONE_TYPE_COMMON_PROPRIETARY_BEEP | 200 | 专有声调，一般蜂鸣声。 | 4033| TONE_TYPE_COMMON_PROPRIETARY_ACK | 201 | 专有声调，ACK。 | 4034| TONE_TYPE_COMMON_PROPRIETARY_PROMPT | 203 | 专有声调，PROMPT。 | 4035| TONE_TYPE_COMMON_PROPRIETARY_DOUBLE_BEEP | 204 | 专有声调，双重蜂鸣声。 | 4036 4037## TonePlayer<sup>9+</sup> 4038 4039提供播放和管理DTMF（Dual Tone Multi Frequency，双音多频）音调的方法，包括各种系统监听音调、专有音调，如拨号音、通话回铃音等。 4040在调用TonePlayer的接口前，需要先通过[createTonePlayer](#audiocreatetoneplayer9)创建实例。 4041 4042**系统接口：** 该接口为系统接口。 4043 4044### load<sup>9+</sup> 4045 4046load(type: ToneType, callback: AsyncCallback<void>): void 4047 4048加载DTMF音调配置。使用callback异步回调。 4049 4050**系统接口：** 该接口为系统接口。 4051 4052**系统能力：** SystemCapability.Multimedia.Audio.Tone 4053 4054**参数：** 4055 4056| 参数名 | 类型 | 必填 | 说明 | 4057| :--------------| :-------------------------- | :-----| :------------------------------ | 4058| type | [ToneType](#tonetype9) | 是 | 配置的音调类型。 | 4059| callback | AsyncCallback<void\> | 是 | 回调函数。当加载DTMF音调配置成功，err为undefined，否则为错误对象。 | 4060 4061**示例：** 4062 4063```ts 4064import { BusinessError } from '@kit.BasicServicesKit'; 4065 4066tonePlayer.load(audio.ToneType.TONE_TYPE_DIAL_5, (err: BusinessError) => { 4067 if (err) { 4068 console.error(`callback call load failed error: ${err.message}`); 4069 return; 4070 } else { 4071 console.info('callback call load success'); 4072 } 4073}); 4074``` 4075 4076### load<sup>9+</sup> 4077 4078load(type: ToneType): Promise<void> 4079 4080加载DTMF音调配置。使用Promise异步回调。 4081 4082**系统接口：** 该接口为系统接口。 4083 4084**系统能力：** SystemCapability.Multimedia.Audio.Tone 4085 4086**参数：** 4087 4088| 参数名 | 类型 | 必填 | 说明 | 4089| :------------- | :--------------------- | :--- | ---------------- | 4090| type | [ToneType](#tonetype9) | 是 | 配置的音调类型。 | 4091 4092**返回值：** 4093 4094| 类型 | 说明 | 4095| :--------------| :-------------------------- | 4096| Promise<void\> | Promise对象。无返回结果的Promise对象。 | 4097 4098**示例：** 4099 4100```ts 4101tonePlayer.load(audio.ToneType.TONE_TYPE_DIAL_1).then(() => { 4102 console.info('promise call load '); 4103}).catch(() => { 4104 console.error('promise call load fail'); 4105}); 4106``` 4107 4108### start<sup>9+</sup> 4109 4110start(callback: AsyncCallback<void>): void 4111 4112启动DTMF音调播放。使用callback异步回调。 4113 4114**系统接口：** 该接口为系统接口。 4115 4116**系统能力：** SystemCapability.Multimedia.Audio.Tone 4117 4118**参数：** 4119 4120| 参数名 | 类型 | 必填 | 说明 | 4121| :------- | :------------------- | :--- | :----------------------------- | 4122| callback | AsyncCallback<void\> | 是 | 回调函数。当启动DTMF音调播放成功，err为undefined，否则为错误对象。 | 4123 4124**示例：** 4125 4126```ts 4127import { BusinessError } from '@kit.BasicServicesKit'; 4128 4129tonePlayer.start((err: BusinessError) => { 4130 if (err) { 4131 console.error(`callback call start failed error: ${err.message}`); 4132 return; 4133 } else { 4134 console.info('callback call start success'); 4135 } 4136}); 4137``` 4138 4139### start<sup>9+</sup> 4140 4141start(): Promise<void> 4142 4143启动DTMF音调播放。使用Promise异步回调。 4144 4145**系统接口：** 该接口为系统接口。 4146 4147**系统能力：** SystemCapability.Multimedia.Audio.Tone 4148 4149**返回值：** 4150 4151| 类型 | 说明 | 4152| :------------- | :---------------------------- | 4153| Promise<void\> | Promise对象。无返回结果的Promise对象。 | 4154 4155**示例：** 4156 4157```ts 4158tonePlayer.start().then(() => { 4159 console.info('promise call start'); 4160}).catch(() => { 4161 console.error('promise call start fail'); 4162}); 4163``` 4164 4165### stop<sup>9+</sup> 4166 4167stop(callback: AsyncCallback<void>): void 4168 4169停止当前正在播放的音调。使用callback异步回调。 4170 4171**系统接口：** 该接口为系统接口。 4172 4173**系统能力：** SystemCapability.Multimedia.Audio.Tone 4174 4175**参数：** 4176 4177| 参数名 | 类型 | 必填 | 说明 | 4178| :------- | :------------------- | :--- | :----------------------------- | 4179| callback | AsyncCallback<void\> | 是 | 回调函数。当停止当前正在播放的音调成功，err为undefined，否则为错误对象。 | 4180 4181**示例：** 4182 4183```ts 4184import { BusinessError } from '@kit.BasicServicesKit'; 4185 4186tonePlayer.stop((err: BusinessError) => { 4187 if (err) { 4188 console.error(`callback call stop error: ${err.message}`); 4189 return; 4190 } else { 4191 console.error('callback call stop success '); 4192 } 4193}); 4194``` 4195 4196### stop<sup>9+</sup> 4197 4198stop(): Promise<void> 4199 4200停止当前正在播放的音调。使用Promise异步回调。 4201 4202**系统接口：** 该接口为系统接口。 4203 4204**系统能力：** SystemCapability.Multimedia.Audio.Tone 4205 4206**返回值：** 4207 4208| 类型 | 说明 | 4209| :------------- | :---------------------------- | 4210| Promise<void\> | Promise对象。无返回结果的Promise对象。 | 4211 4212**示例：** 4213 4214```ts 4215tonePlayer.stop().then(() => { 4216 console.info('promise call stop finish'); 4217}).catch(() => { 4218 console.error('promise call stop fail'); 4219}); 4220``` 4221 4222### release<sup>9+</sup> 4223 4224release(callback: AsyncCallback<void>): void 4225 4226释放与此TonePlayer对象关联的资源。使用callback异步回调。 4227 4228**系统接口：** 该接口为系统接口。 4229 4230**系统能力：** SystemCapability.Multimedia.Audio.Tone 4231 4232**参数：** 4233 4234| 参数名 | 类型 | 必填 | 说明 | 4235| :------- | :------------------- | :--- | :---------------------------- | 4236| callback | AsyncCallback<void\> | 是 | 回调函数。当释放与此TonePlayer对象关联的资源成功，err为undefined，否则为错误对象。 | 4237 4238**示例：** 4239 4240```ts 4241import { BusinessError } from '@kit.BasicServicesKit'; 4242 4243tonePlayer.release((err: BusinessError) => { 4244 if (err) { 4245 console.error(`callback call release failed error: ${err.message}`); 4246 return; 4247 } else { 4248 console.info('callback call release success '); 4249 } 4250}); 4251``` 4252 4253### release<sup>9+</sup> 4254 4255release(): Promise<void> 4256 4257释放与此TonePlayer对象关联的资源。使用Promise异步回调。 4258 4259**系统接口：** 该接口为系统接口。 4260 4261**系统能力：** SystemCapability.Multimedia.Audio.Tone 4262 4263**返回值：** 4264 4265| 类型 | 说明 | 4266| :------------- | :---------------------------- | 4267| Promise<void\> | Promise对象。无返回结果的Promise对象。 | 4268 4269**示例：** 4270 4271```ts 4272tonePlayer.release().then(() => { 4273 console.info('promise call release'); 4274}).catch(() => { 4275 console.error('promise call release fail'); 4276}); 4277``` 4278 4279## AsrProcessingController<sup>12+</sup> 4280 4281ASR处理控制器 4282 4283**系统接口：** 该接口为系统接口。 4284 4285**系统能力：** SystemCapability.Multimedia.Audio.Capturer 4286 4287### setAsrAecMode<sup>12+</sup> 4288 4289setAsrAecMode(mode: AsrAecMode): boolean 4290 4291设置ASR AEC模式，同步返回结果。 4292 4293**系统接口：** 该接口为系统接口。 4294 4295**系统能力：** SystemCapability.Multimedia.Audio.Capturer 4296 4297**参数：** 4298 4299| 参数名| 类型 | 必填 | 说明 | 4300|-------|----------------------------|-------|-------| 4301| mode | [AsrAecMode](#asraecmode12) | 是 |ASR AEC 模式。 | 4302 4303**返回值：** 4304 4305| 类型 | 说明 | 4306|-------|---------------------------------------| 4307| boolean | 返回设置ASR AEC模式结果，true为设置成功，false为设置失败。 | 4308 4309**错误码：** 4310 4311以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 4312 4313| 错误码ID | 错误信息 | 4314|---------|------------------------------------------| 4315| 202 | Caller is not a system application. | 4316| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4317| 6800101 | Parameter verification failed. | 4318| 6800104 | Operation not allowed. | 4319 4320**示例：** 4321 4322```ts 4323let flag = asrProcessingController.setAsrAecMode(audio.AsrAecMode.BYPASS); 4324``` 4325 4326### getAsrAecMode<sup>12+</sup> 4327 4328getAsrAecMode(): AsrAecMode 4329 4330获取ASR AEC模式，同步返回结果。 4331 4332**系统接口：** 该接口为系统接口。 4333 4334**系统能力：** SystemCapability.Multimedia.Audio.Capturer 4335 4336**返回值：** 4337 4338| 类型 | 说明 | 4339|-------|-------| 4340| [AsrAecMode](#asraecmode12) |ASR AEC 模式 | 4341 4342**错误码：** 4343 4344以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 4345 4346| 错误码ID | 错误信息 | 4347|---------|------------------------------------------| 4348| 202 | Caller is not a system application. | 4349| 6800104 | Operation not allowed. | 4350 4351 4352**示例：** 4353 4354```ts 4355let mode = asrProcessingController.getAsrAecMode(); 4356``` 4357 4358### setAsrNoiseSuppressionMode<sup>12+</sup> 4359 4360setAsrNoiseSuppressionMode(mode: AsrNoiseSuppressionMode): boolean 4361 4362设置ASR 噪音抑制模式，同步返回结果。 4363 4364**系统接口：** 该接口为系统接口。 4365 4366**系统能力：** SystemCapability.Multimedia.Audio.Capturer 4367 4368**参数：** 4369 4370| 参数名| 类型 | 必填 | 说明 | 4371|-------|-------------------------------------------------------|-------|-------| 4372| mode | [AsrNoiseSuppressionMode](#asrnoisesuppressionmode12) | 是 |ASR 噪音抑制模式。 | 4373 4374**返回值：** 4375 4376| 类型 | 说明 | 4377|-------|----------------------------------------| 4378| boolean | 返回设置ASR 噪音抑制模式结果，true为设置成功，false为设置失败。 | 4379 4380**错误码：** 4381 4382以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 4383 4384| 错误码ID | 错误信息 | 4385|---------|------------------------------------------| 4386| 202 | Caller is not a system application. | 4387| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4388| 6800101 | Parameter verification failed. | 4389| 6800104 | Operation not allowed. | 4390 4391**示例：** 4392 4393```ts 4394let flag = asrProcessingController.setAsrNoiseSuppressionMode(audio.AsrNoiseSuppressionMode.BYPASS); 4395``` 4396 4397### getAsrNoiseSuppressionMode<sup>12+</sup> 4398 4399getAsrNoiseSuppressionMode(): AsrNoiseSuppressionMode 4400 4401获取ASR 噪音抑制模式，同步返回结果。 4402 4403**系统接口：** 该接口为系统接口。 4404 4405**系统能力：** SystemCapability.Multimedia.Audio.Capturer 4406 4407**返回值：** 4408 4409| 类型 |说明 | 4410|-------------------------|-------| 4411| [AsrNoiseSuppressionMode](#asrnoisesuppressionmode12) |ASR 噪音抑制模式。 | 4412 4413**错误码：** 4414 4415以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 4416 4417| 错误码ID | 错误信息 | 4418|---------|------------------------------------------| 4419| 202 | Caller is not a system application. | 4420| 6800104 | Operation not allowed. | 4421 4422**示例：** 4423 4424```ts 4425let mode = asrProcessingController.getAsrNoiseSuppressionMode(); 4426``` 4427 4428### isWhispering<sup>12+</sup> 4429 4430isWhispering(): boolean 4431 4432查询耳语状态。 4433 4434**系统接口：** 该接口为系统接口。 4435 4436**系统能力：** SystemCapability.Multimedia.Audio.Capturer 4437 4438**返回值：** 4439 4440| 类型 | 说明 | 4441|-------|--------------------------| 4442| boolean | 返回耳语状态，true为开启，false为关闭。 | 4443 4444**错误码：** 4445 4446以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 4447 4448| 错误码ID | 错误信息 | 4449|---------|------------------------------------------| 4450| 202 | Caller is not a system application. | 4451| 6800104 | Operation not allowed. | 4452 4453**示例：** 4454 4455```ts 4456let flag = asrProcessingController.isWhispering(); 4457``` 4458 4459### setAsrWhisperDetectionMode<sup>12+</sup> 4460 4461setAsrWhisperDetectionMode(mode: AsrWhisperDetectionMode): boolean 4462 4463设置耳语检测模式。 4464 4465**系统接口：** 该接口为系统接口。 4466 4467**系统能力：** SystemCapability.Multimedia.Audio.Capturer 4468 4469**参数：** 4470 4471| 参数名 | 类型 | 必填 | 说明 | 4472|------|---------------------|-------|--------| 4473| mode | [AsrWhisperDetectionMode](#asrwhisperdetectionmode12) | 是 | 耳语检测模式。 | 4474 4475**返回值：** 4476 4477| 类型 | 说明 | 4478|-------|----------------------------------------| 4479| boolean | 返回设置耳语检测模式结果，true为设置成功，false为设置失败。 | 4480 4481**错误码：** 4482 4483以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 4484 4485| 错误码ID | 错误信息 | 4486|---------|------------------------------------------| 4487| 202 | Caller is not a system application. | 4488| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified; 2.Incorrect parameter types. | 4489| 6800101 | Parameter verification failed. | 4490| 6800104 | Operation not allowed. | 4491 4492**示例：** 4493 4494```ts 4495let flag = asrProcessingController.setAsrWhisperDetectionMode(audio.AsrWhisperDetectionMode.BYPASS); 4496``` 4497 4498 4499### getAsrWhisperDetectionMode<sup>12+</sup> 4500 4501getAsrWhisperDetectionMode(): AsrWhisperDetectionMode 4502 4503获取耳语检测模式，同步返回结果。 4504 4505**系统接口：** 该接口为系统接口。 4506 4507**系统能力：** SystemCapability.Multimedia.Audio.Capturer 4508 4509**返回值：** 4510 4511| 类型 | 说明 | 4512|-------|--------| 4513| [AsrWhisperDetectionMode](#asrwhisperdetectionmode12) | 耳语检测模式。 | 4514 4515**错误码：** 4516 4517以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 4518 4519| 错误码ID | 错误信息 | 4520|---------|------------------------------------------| 4521| 202 | Caller is not a system application. | 4522| 6800104 | Operation not allowed. | 4523 4524**示例：** 4525 4526```ts 4527let mode = asrProcessingController.getAsrWhisperDetectionMode(); 4528``` 4529 4530 4531### setAsrVoiceControlMode<sup>12+</sup> 4532 4533setAsrVoiceControlMode(mode: AsrVoiceControlMode, enable: boolean): boolean 4534 4535设置在系统通话中上报mode及通话录音的上行通路的ASR音频通路选择。 4536 4537**系统接口：** 该接口为系统接口。 4538 4539**系统能力：** SystemCapability.Multimedia.Audio.Capturer 4540 4541**参数：** 4542 4543| 参数名 | 类型 | 必填 | 说明 | 4544|------|---------------------|-------|--------| 4545| mode | [AsrVoiceControlMode](#asrvoicecontrolmode12) | 是 | 音频通路模式。 | 4546| enable | boolean | 是 | 表示系统通话中上报mode及通话录音的上行通路的ASR音频通路选择开关状态。true表示打开，false表示关闭。 | 4547 4548**返回值：** 4549 4550| 类型 | 说明 | 4551|-------|---------------------------------------------------------------| 4552| boolean | 返回设置在系统通话中上报mode及通话录音的上行通路的ASR音频通路选择的结果。true为设置成功，false为设置失败。 | 4553 4554**错误码：** 4555 4556以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 4557 4558| 错误码ID | 错误信息 | 4559|---------|------------------------------------------| 4560| 202 | Caller is not a system application. | 4561| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified; 2.Incorrect parameter types. | 4562| 6800101 | Parameter verification failed. | 4563| 6800104 | Operation not allowed. | 4564 4565**示例：** 4566 4567```ts 4568let flag = asrProcessingController.setAsrVoiceControlMode(audio.AsrVoiceControlMode.AUDIO_2_VOICE_TX, true); 4569``` 4570 4571### setAsrVoiceMuteMode<sup>12+</sup> 4572 4573setAsrVoiceMuteMode(mode: AsrVoiceMuteMode, enable: boolean): boolean 4574 4575在系统通话中，对ASR音频通路进行静音控制。 4576 4577**系统接口：** 该接口为系统接口。 4578 4579**系统能力：** SystemCapability.Multimedia.Audio.Capturer 4580 4581**参数：** 4582 4583| 参数名 | 类型 | 必填 | 说明 | 4584|------|---------------------------------------|-------|----------| 4585| mode | [AsrVoiceMuteMode](#asrvoicemutemode12) | 是 | 静音控制模式。 | 4586| enable | boolean | 是 | 表示在系统通话中设置ASR音频通路静音状态。true表示静音，false表示非静音。 | 4587 4588**返回值：** 4589 4590| 类型 | 说明 | 4591|-------|--------------------------------------------------| 4592| boolean | 返回在系统通话中，对ASR音频通路进行静音控制的结果。true为设置成功，false为设置失败。 | 4593 4594**错误码：** 4595 4596以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 4597 4598| 错误码ID | 错误信息 | 4599|---------|------------------------------------------| 4600| 202 | Caller is not a system application. | 4601| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified; 2.Incorrect parameter types. | 4602| 6800101 | Parameter verification failed. | 4603| 6800104 | Operation not allowed. | 4604 4605**示例：** 4606 4607```ts 4608let flag = asrProcessingController.setAsrVoiceMuteMode(audio.AsrVoiceMuteMode.OUTPUT_MUTE, true); 4609```