1# @ohos.multimedia.audio (音频管理)(系统接口) 2 3音频管理提供管理音频的一些基础能力，包括对音频音量、音频设备的管理，以及对音频数据的采集和渲染等。 4 5该模块提供以下音频相关的常用功能： 6 7- [AudioManager](#audiomanager)：音频管理。 8- [TonePlayer](#toneplayer9)：用于管理和播放DTMF（Dual Tone Multi Frequency，双音多频）音调，如拨号音、通话回铃音等。 9 10> **说明：** 11> 12> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 13> - 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.multimedia.audio (音频管理)](js-apis-audio.md)。 14 15## 导入模块 16 17```ts 18import { audio } from '@kit.AudioKit'; 19``` 20 21## 常量 22 23| 名称 | 类型 | 可读 | 可写 | 说明 | 24| --------------------------------------- | ----------| ---- | ---- | ------------------ | 25| LOCAL_NETWORK_ID<sup>9+</sup> | string | 是 | 否 | 本地设备网络id。<br/>此接口为系统接口。<br> **系统能力：** SystemCapability.Multimedia.Audio.Device | 26 27## audio.createTonePlayer<sup>9+</sup> 28 29createTonePlayer(options: AudioRendererInfo, callback: AsyncCallback<TonePlayer>): void 30 31创建DTMF播放器。使用callback方式异步返回结果。 32 33**系统能力：** SystemCapability.Multimedia.Audio.Tone 34 35**系统接口：** 该接口为系统接口 36 37**参数：** 38 39| 参数名 | 类型 | 必填 | 说明 | 40| -------- | ----------------------------------------------- | ---- | -------------- | 41| options | [AudioRendererInfo](js-apis-audio.md#audiorendererinfo8) | 是 | 配置音频渲染器信息。| 42| callback | AsyncCallback<[TonePlayer](#toneplayer9)> | 是 | 回调函数。当获取DTMF播放器成功，err为undefined，data为获取到的DTMF播放器对象；否则为错误对象。| 43 44**示例：** 45 46```ts 47import { audio } from '@kit.AudioKit'; 48 49let audioRendererInfo: audio.AudioRendererInfo = { 50 usage : audio.StreamUsage.STREAM_USAGE_DTMF, 51 rendererFlags : 0 52}; 53let tonePlayer: audio.TonePlayer; 54 55audio.createTonePlayer(audioRendererInfo, (err, data) => { 56 console.info(`callback call createTonePlayer: audioRendererInfo: ${audioRendererInfo}`); 57 if (err) { 58 console.error(`callback call createTonePlayer return error: ${err.message}`); 59 } else { 60 console.info(`callback call createTonePlayer return data: ${data}`); 61 tonePlayer = data; 62 } 63}); 64``` 65 66## audio.createTonePlayer<sup>9+</sup> 67 68createTonePlayer(options: AudioRendererInfo): Promise<TonePlayer> 69 70创建DTMF播放器。使用Promise方式异步返回结果。 71 72**系统能力：** SystemCapability.Multimedia.Audio.Tone 73 74**系统接口：** 该接口为系统接口 75 76**参数：** 77 78| 参数名 | 类型 | 必填 | 说明 | 79| :------ | :---------------------------------------------| :--- | :----------- | 80| options | [AudioRendererInfo](js-apis-audio.md#audiorendererinfo8) | 是 | 配置音频渲染器信息。 | 81 82**返回值：** 83 84| 类型 | 说明 | 85| ----------------------------------------- | -------------------------------- | 86| Promise<[TonePlayer](#toneplayer9)> | Promise对象，返回DTMF播放器对象。 | 87 88**示例：** 89 90```ts 91import { audio } from '@kit.AudioKit'; 92 93let tonePlayer: audio.TonePlayer; 94async function createTonePlayerBefore(){ 95 let audioRendererInfo: audio.AudioRendererInfo = { 96 usage : audio.StreamUsage.STREAM_USAGE_DTMF, 97 rendererFlags : 0 98 }; 99 tonePlayer = await audio.createTonePlayer(audioRendererInfo); 100} 101``` 102 103## audio.createAsrProcessingController<sup>12+</sup> 104 105createAsrProcessingController(audioCapturer: AudioCapturer): AsrProcessingController; 106 107获取ASR处理控制器 108 109**系统接口：** 该接口为系统接口 110 111**系统能力：** SystemCapability.Multimedia.Audio.Capturer 112 113**返回值：** 114 115| 类型 | 说明 | 116|-------------------------------------------------------| ------------ | 117| [AsrProcessingController](#asrprocessingcontroller12) | ASR处理控制器对象。 | 118 119**错误码：** 120 121以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 122 123| 错误码ID | 错误信息 | 124|---------|------------------------------------------| 125| 202 | Caller is not a system application. | 126| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 127| 6800101 | Parameter verification failed. | 128| 6800104 | Operation not allowed. | 129 130**示例：** 131 132```ts 133import { audio } from '@kit.AudioKit'; 134 135let audioStreamInfo: audio.AudioStreamInfo = { 136 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100, 137 channels: audio.AudioChannel.CHANNEL_2, 138 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 139 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 140}; 141 142let audioCapturerInfo: audio.AudioCapturerInfo = { 143 source: audio.SourceType.SOURCE_TYPE_MIC, 144 capturerFlags: 0 145}; 146 147let audioCapturerOptions: audio.AudioCapturerOptions = { 148 streamInfo: audioStreamInfo, 149 capturerInfo: audioCapturerInfo 150}; 151 152audio.createAudioCapturer(audioCapturerOptions, (err, data) => { 153 if (err) { 154 console.error(`AudioCapturer Created : Error: ${err}`); 155 } else { 156 console.info('AudioCapturer Created : Success : SUCCESS'); 157 let audioCapturer = data; 158 let asrProcessingController = audio.createAsrProcessingController(audioCapturer); 159 console.info('AsrProcessingController Created : Success : SUCCESS'); 160 } 161}); 162``` 163 164## AudioVolumeType 165 166枚举，音频流类型。 167 168**系统能力：** SystemCapability.Multimedia.Audio.Volume 169 170| 名称 | 值 | 说明 | 171| ---------------------------- | ------ | ---------- | 172| ULTRASONIC<sup>10+</sup> | 10 | 超声波。<br/>此接口为系统接口。| 173| ALL<sup>9+</sup> | 100 | 所有公共音频流。<br/>此接口为系统接口。| 174 175## InterruptRequestResultType<sup>9+</sup> 176 177枚举，音频中断请求结果类型。 178 179**系统能力：** SystemCapability.Multimedia.Audio.Interrupt 180 181**系统接口：** 该接口为系统接口 182 183| 名称 | 值 | 说明 | 184| ---------------------------- | ------ | ---------- | 185| INTERRUPT_REQUEST_GRANT | 0 | 请求音频中断成功。 | 186| INTERRUPT_REQUEST_REJECT | 1 | 请求音频中断失败，可能具有较高优先级类型。 | 187 188## DeviceFlag 189 190枚举，可获取的设备种类。 191 192**系统能力：** SystemCapability.Multimedia.Audio.Device 193 194| 名称 | 值 | 说明 | 195| ------------------------------- | ------ |---------------------------| 196| NONE_DEVICES_FLAG<sup>9+</sup> | 0 | 无设备。 <br/>此接口为系统接口。 | 197| DISTRIBUTED_OUTPUT_DEVICES_FLAG<sup>9+</sup> | 4 | 分布式输出设备。<br/>此接口为系统接口。 | 198| DISTRIBUTED_INPUT_DEVICES_FLAG<sup>9+</sup> | 8 | 分布式输入设备。<br/>此接口为系统接口。 | 199| ALL_DISTRIBUTED_DEVICES_FLAG<sup>9+</sup> | 12 | 分布式输入和输出设备。<br/>此接口为系统接口。 | 200 201 202## StreamUsage 203 204枚举，音频流使用类型。 205 206**系统能力：** SystemCapability.Multimedia.Audio.Core 207 208| 名称 | 值 | 说明 | 209| ------------------------------------------| ------ |---------------------------------------------------------------------------------------------------------------------------------------------| 210| STREAM_USAGE_SYSTEM<sup>10+</sup> | 9 | 系统音(如屏幕锁定或按键音)。<br/>此接口为系统接口。 | 211| STREAM_USAGE_DTMF<sup>10+</sup> | 14 | 拨号音。<br/>此接口为系统接口。 | 212| STREAM_USAGE_ENFORCED_TONE<sup>10+</sup> | 15 | 强制音(如相机快门音)。<br/>此接口为系统接口。 | 213| STREAM_USAGE_ULTRASONIC<sup>10+</sup> | 16 | 超声波（目前仅提供给MSDP使用）。<br/>此接口为系统接口。 | 214| STREAM_USAGE_VOICE_CALL_ASSISTANT<sup>12+</sup> | 21 | 通话辅助语音。<br/>此接口为系统接口。 | 215 216## InterruptRequestType<sup>9+</sup> 217 218枚举，音频中断请求类型。 219 220**系统接口：** 该接口为系统接口 221 222**系统能力：** SystemCapability.Multimedia.Audio.Interrupt 223 224| 名称 | 值 | 说明 | 225| ---------------------------------- | ------ | ------------------------- | 226| INTERRUPT_REQUEST_TYPE_DEFAULT | 0 | 默认类型，可中断音频请求。 | 227 228## VolumeFlag<sup>12+</sup> 229 230枚举，音量相关操作。 231 232**系统接口：** 该接口为系统接口 233 234**系统能力：** SystemCapability.Multimedia.Audio.Volume 235 236| 名称 | 值 | 说明 | 237| ---------------------------------- |---|----------| 238| FLAG_SHOW_SYSTEM_UI | 1 | 拉起系统音量条。 | 239 240## AsrNoiseSuppressionMode<sup>12+</sup> 241 242枚举，ASR 噪音抑制模式 243 244**系统接口：** 该接口为系统接口 245 246**系统能力：** SystemCapability.Multimedia.Audio.Capturer 247 248| 名称| 值 | 说明 | 249|-------|-------|-------| 250| BYPASS | 0 |旁路噪音抑制| 251| STANDARD | 1 |标准噪音抑制| 252| NEAR_FIELD | 2 |近场噪音抑制| 253| FAR_FIELD | 3 |远场噪音抑制| 254 255## AsrAecMode<sup>12+</sup> 256 257枚举，ASR AEC 模式 258 259**系统接口：** 该接口为系统接口 260 261**系统能力：** SystemCapability.Multimedia.Audio.Capturer 262 263| 名称| 值 | 说明 | 264|-------|-------|-------| 265| BYPASS | 0 |BYPASS AEC| 266| STANDARD | 1 |STANDARD AEC| 267 268## AsrWhisperDetectionMode<sup>12+</sup> 269 270枚举，ASR（Automatic Speech Recognition，自动语音识别）耳语检测模式。 271 272**系统接口：** 该接口为系统接口 273 274**系统能力：** SystemCapability.Multimedia.Audio.Capturer 275 276| 名称 | 值 | 说明 | 277|-----|---|----------| 278| BYPASS | 0 | 不启用检测模型。 | 279| STANDARD | 1 | 耳语检测模型。 | 280 281## AsrVoiceControlMode<sup>12+</sup> 282 283枚举，ASR音频通路模式。 284 285**系统接口：** 该接口为系统接口 286 287**系统能力：** SystemCapability.Multimedia.Audio.Capturer 288 289| 名称 | 值 | 说明 | 290|-------------------------|---|---------------------------------------| 291| AUDIO_2_VOICE_TX | 0 | 仅媒体音频流生效。 | 292| AUDIO_MIX_2_VOICE_TX | 1 | 媒体音频流和MIC音频流均生效。 | 293| AUDIO_2_VOICE_TX_EX | 2 | 仅媒体音频流生效，将媒体流上报给通话录音。 | 294| AUDIO_MIX_2_VOICE_TX_EX | 3 | 媒体音频流和MIC音频流均生效，将媒体流上报给通话录音。 | 295 296## AsrVoiceMuteMode<sup>12+</sup> 297 298枚举，ASR静音模式。 299 300**系统接口：** 该接口为系统接口 301 302**系统能力：** SystemCapability.Multimedia.Audio.Capturer 303 304| 名称 | 值 | 说明 | 305|----------------|---|---------------------| 306| OUTPUT_MUTE | 0 | 本地输出静音。 | 307| INPUT_MUTE | 1 | 本地的MIC输入静音。 | 308| TTS_MUTE | 2 | 应用下发的媒体音频本地静音。 | 309| CALL_MUTE | 3 | 通话语音流静音。 | 310| OUTPUT_MUTE_EX | 4 | 本地输出静音，媒体音频流送给通话录音。 | 311 312## InterruptResult<sup>9+</sup> 313 314音频中断结果。 315 316**系统能力：** SystemCapability.Multimedia.Audio.Interrupt 317 318**系统接口：** 该接口为系统接口 319 320| 名称 | 类型 | 必填 | 说明 | 321| --------------| -------------------------------------------------------------- | ---- | ---------------- | 322| requestResult | [InterruptRequestResultType](#interruptrequestresulttype9) | 是 | 表示音频请求中断类型。 | 323| interruptNode | number | 是 | 音频请求中断的节点。 | 324 325## VolumeEvent<sup>9+</sup> 326 327音量改变时，应用接收的事件。 328 329**系统能力：** SystemCapability.Multimedia.Audio.Volume 330 331| 名称 | 类型 | 必填 | 说明 | 332| ---------- | ----------------------------------- | ---- |-------------------------------------------| 333| volumeGroupId | number | 是 | 音量组id，可用于getGroupManager入参。<br/>此接口为系统接口。 | 334| networkId | string | 是 | 网络id。<br/>此接口为系统接口。 | 335 336## ConnectType<sup>9+</sup> 337 338枚举，设备连接类型。 339 340**系统接口：** 该接口为系统接口 341 342**系统能力：** SystemCapability.Multimedia.Audio.Volume 343 344| 名称 | 值 | 说明 | 345| :------------------------------ | :----- | :--------------------- | 346| CONNECT_TYPE_LOCAL | 1 | 本地设备。 | 347| CONNECT_TYPE_DISTRIBUTED | 2 | 分布式设备。 | 348 349## VolumeGroupInfos<sup>9+</sup> 350 351音量组信息，数组类型，为[VolumeGroupInfo](#volumegroupinfo9)的数组，只读。 352 353**系统接口：** 该接口为系统接口 354 355**系统能力：** SystemCapability.Multimedia.Audio.Volume 356 357## VolumeGroupInfo<sup>9+</sup> 358 359音量组信息。 360 361**系统接口：** 该接口为系统接口 362 363**系统能力：** SystemCapability.Multimedia.Audio.Volume 364 365| 名称 | 类型 | 可读 | 可写 | 说明 | 366| -------------------------- | -------------------------- | ---- | ---- | ---------- | 367| networkId<sup>9+</sup> | string | 是 | 否 | 组网络id。 | 368| groupId<sup>9+</sup> | number | 是 | 否 | 组设备组id。 | 369| mappingId<sup>9+</sup> | number | 是 | 否 | 组映射id。 | 370| groupName<sup>9+</sup> | string | 是 | 否 | 组名。 | 371| type<sup>9+</sup> | [ConnectType](#connecttype9)| 是 | 否 | 连接设备类型。 | 372 373## SourceType<sup>8+</sup> 374 375枚举，音源类型。 376 377| 名称 | 值 | 说明 | 378| :------------------------------------------- | :----- | :--------------------- | 379| SOURCE_TYPE_WAKEUP <sup>10+</sup> | 3 | 语音唤醒音频流录制音频源。<br/>**系统能力：** SystemCapability.Multimedia.Audio.Core <br/>**需要权限：** ohos.permission.MANAGE_INTELLIGENT_VOICE <br/> 此接口为系统接口| 380| SOURCE_TYPE_VOICE_CALL<sup>11+</sup> | 4 | 通话录音的音频源。<br/>**系统能力：** SystemCapability.Multimedia.Audio.Core<br/>**需要权限：** ohos.permission.RECORD_VOICE_CALL <br/> 此接口为系统接口| 381 382## VolumeAdjustType<sup>10+</sup> 383 384枚举，音量调节类型。 385 386**系统接口：** 该接口为系统接口 387 388**系统能力：** SystemCapability.Multimedia.Audio.Volume 389 390| 名称 | 值 | 说明 | 391| :--------------------- | :----- | :-------------------------------------------- | 392| VOLUME_UP | 0 | 向上调节音量。<br/>此接口为系统接口。 | 393| VOLUME_DOWN | 1 | 向下调节音量。<br/>此接口为系统接口。 | 394 395## AudioManager 396 397管理音频音量和音频设备。在调用AudioManager的接口前，需要先通过[getAudioManager](js-apis-audio.md#audiogetaudiomanager)创建实例。 398 399### setExtraParameters<sup>11+</sup> 400 401setExtraParameters(mainKey: string, kvpairs: Record<string, string\>): Promise<void> 402 403音频扩展参数设置，使用Promise方式异步返回结果。 404 405**需要权限：** ohos.permission.MODIFY_AUDIO_SETTINGS 406 407**系统接口：** 该接口为系统接口 408 409**系统能力：** SystemCapability.Multimedia.Audio.Core 410 411**参数：** 412 413| 参数名 | 类型 | 必填 | 说明 | 414| ------ | ------ | ---- | ---------------------- | 415| mainKey | string | 是 | 被设置的音频参数的主键。 | 416| kvpairs | Record<string, string\> | 是 | 被设置的音频参数的子键值对。 | 417 418**返回值：** 419 420| 类型 | 说明 | 421| ------------------- | ------------------------------- | 422| Promise<void> | Promise对象，无返回结果。 | 423 424**错误码：** 425 426以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 427 428| 错误码ID | 错误信息 | 429|-----|------------------------------------------------------------------------------------------------------------| 430| 201 | Permission denied. | 431| 202 | Not system App. | 432| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 433| 6800101 | Parameter verification failed. | 434 435**示例：** 436 437```ts 438import { BusinessError } from '@kit.BasicServicesKit'; 439 440let kvpairs = {} as Record<string, string>; 441kvpairs = { 442 'key_example': 'value_example' 443}; 444 445audioManager.setExtraParameters('key_example', kvpairs).then(() => { 446 console.info('Promise returned to indicate a successful setting of the extra parameters.'); 447}).catch ((err: BusinessError) => { 448 console.error(`Failed to set the audio extra parameters ${err}`); 449}); 450``` 451 452### getExtraParameters<sup>11+</sup> 453 454getExtraParameters(mainKey: string, subKeys?: Array\<string>): Promise\<Record\<string, string>> 455 456获取指定音频参数值，使用Promise方式异步返回结果。 457 458**系统接口：** 该接口为系统接口 459 460**系统能力：** SystemCapability.Multimedia.Audio.Core 461 462**参数：** 463 464| 参数名 | 类型 | 必填 | 说明 | 465| ------ | ------ |--| ---------------------- | 466| mainKey | string | 是 | 待获取的音频参数的主键。 | 467| subKeys | Array\<string> | 否 | 待获取的音频参数的子键。 | 468 469**返回值：** 470 471| 类型 | 说明 | 472| --------------------- | ----------------------------------- | 473| Promise\<Record\<string, string>> | Promise对象，返回获取的音频参数的值。 | 474 475**错误码：** 476 477以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 478 479| 错误码ID | 错误信息 | 480| ------ | -------------------------| 481| 202 | Not system App. | 482| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 483| 6800101 | Parameter verification failed. | 484 485**示例：** 486 487```ts 488import { BusinessError } from '@kit.BasicServicesKit'; 489 490let subKeys: Array<String> = ['key_example']; 491audioManager.getExtraParameters('key_example', subKeys).then((value: Record<string, string>) => { 492 console.info(`Promise returned to indicate that the value of the audio extra parameters is obtained ${value}.`); 493}).catch ((err: BusinessError) => { 494 console.error(`Failed to get the audio extra parameters ${err}`); 495}); 496``` 497 498### setAudioScene<sup>8+</sup> 499 500setAudioScene\(scene: AudioScene, callback: AsyncCallback<void\>\): void 501 502设置音频场景模式，使用callback方式异步返回结果。 503 504**系统接口：** 该接口为系统接口 505 506**系统能力：** SystemCapability.Multimedia.Audio.Communication 507 508**参数：** 509 510| 参数名 | 类型 | 必填 | 说明 | 511| :------- | :----------------------------------- | :--- | :------------------- | 512| scene | [AudioScene](js-apis-audio.md#audioscene8) | 是 | 音频场景模式。 | 513| callback | AsyncCallback<void\> | 是 | 回调函数。当设置音频场景模式成功，err为undefined，否则为错误对象。 | 514 515**示例：** 516 517```ts 518import { BusinessError } from '@kit.BasicServicesKit'; 519 520audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL, (err: BusinessError) => { 521 if (err) { 522 console.error(`Failed to set the audio scene mode. ${err}`); 523 return; 524 } 525 console.info('Callback invoked to indicate a successful setting of the audio scene mode.'); 526}); 527``` 528 529### setAudioScene<sup>8+</sup> 530 531setAudioScene\(scene: AudioScene\): Promise<void\> 532 533设置音频场景模式，使用Promise方式返回异步结果。 534 535**系统接口：** 该接口为系统接口 536 537**系统能力：** SystemCapability.Multimedia.Audio.Communication 538 539**参数：** 540 541| 参数名 | 类型 | 必填 | 说明 | 542| :----- | :----------------------------------- | :--- | :------------- | 543| scene | [AudioScene](js-apis-audio.md#audioscene8) | 是 | 音频场景模式。 | 544 545**返回值：** 546 547| 类型 | 说明 | 548| :------------- | :------------------- | 549| Promise<void\> | Promise对象，无返回结果。 | 550 551**示例：** 552 553```ts 554import { BusinessError } from '@kit.BasicServicesKit'; 555 556audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL).then(() => { 557 console.info('Promise returned to indicate a successful setting of the audio scene mode.'); 558}).catch ((err: BusinessError) => { 559 console.error(`Failed to set the audio scene mode ${err}`); 560}); 561``` 562 563### getSpatializationManager<sup>11+</sup> 564 565getSpatializationManager(): AudioSpatializationManager 566 567获取空间音频管理器。 568 569**系统接口：** 该接口为系统接口 570 571**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 572 573**返回值：** 574 575| 类型 | 说明 | 576|------------------------------------------| ----------------------------- | 577| [AudioSpatializationManager](#audiospatializationmanager11) | AudioSpatializationManager实例 | 578 579**错误码：** 580 581以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 582 583| 错误码ID | 错误信息 | 584| ------- | --------------------------------------------| 585| 202 | Not system App. | 586 587**示例：** 588 589```ts 590import { audio } from '@kit.AudioKit'; 591 592let audioSpatializationManager: audio.AudioSpatializationManager = audioManager.getSpatializationManager(); 593``` 594 595### disableSafeMediaVolume<sup>12+</sup> 596 597disableSafeMediaVolume(): Promise<void> 598 599设置安全音量为非激活状态。使用Promise方式异步返回结果。 600 601设置为非激活状态后，当设备长时间高音量播放时，不再自动提醒用户降低到安全音量。 602 603**需要权限：** ohos.permission.MODIFY_AUDIO_SETTINGS 604 605**系统接口：** 该接口为系统接口 606 607**系统能力：** SystemCapability.Multimedia.Audio.Core 608 609**返回值：** 610 611| 类型 | 说明 | 612|------------------------------------------| ----------------------------- | 613| Promise<void> | Promise对象，无返回结果。 | 614 615**错误码：** 616 617以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 618 619| 错误码ID | 错误信息 | 620| ------- | --------------------------------------------| 621| 201 | Permission denied. | 622| 202 | Not system App. | 623 624**示例：** 625 626```ts 627import { BusinessError } from '@kit.BasicServicesKit'; 628 629audioManager.disableSafeMediaVolume().then(() => { 630 console.info('disableSafeMediaVolume success.'); 631}).catch ((err: BusinessError) => { 632 console.error(`disableSafeMediaVolume fail: ${err.code},${err.message}`); 633}); 634``` 635 636### on('volumeChange')<sup>(deprecated)</sup> 637 638on(type: 'volumeChange', callback: Callback\<VolumeEvent>): void 639 640> **说明：** 641> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用AudioVolumeManager中的[on('volumeChange')](js-apis-audio.md#onvolumechange9)替代。 642 643监听系统音量变化事件（当系统音量发生变化时触发），使用callback方式返回结果。 644 645**系统接口：** 该接口为系统接口 646 647目前此订阅接口在单进程多AudioManager实例的使用场景下，仅最后一个实例的订阅生效，其他实例的订阅会被覆盖（即使最后一个实例没有进行订阅），因此推荐使用单一AudioManager实例进行开发。 648 649**系统能力：** SystemCapability.Multimedia.Audio.Volume 650 651**参数：** 652 653| 参数名 | 类型 | 必填 | 说明 | 654| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 655| type | string | 是 | 监听事件，固定为：'volumeChange'。 | 656| callback | Callback<[VolumeEvent](#volumeevent9)> | 是 | 回调函数，返回变化后的音量信息。 | 657 658**示例：** 659 660```ts 661audioManager.on('volumeChange', (volumeEvent: audio.VolumeEvent) => { 662 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 663 console.info(`Volume level: ${volumeEvent.volume} `); 664 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 665}); 666``` 667 668### on('ringerModeChange')<sup>(deprecated)</sup> 669 670on(type: 'ringerModeChange', callback: Callback\<AudioRingMode>): void 671 672监听铃声模式变化事件（当[铃声模式](js-apis-audio.md#audioringmode)发生改变时触发），使用callback方式返回结果。 673 674> **说明：** 675> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用AudioVolumeGroupManager中的[on('ringerModeChange')](js-apis-audio.md#onringermodechange9)替代。 676 677**系统接口：** 该接口为系统接口 678 679**系统能力：** SystemCapability.Multimedia.Audio.Communication 680 681**参数：** 682 683| 参数名 | 类型 | 必填 | 说明 | 684| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 685| type | string | 是 | 监听事件，固定为：'ringerModeChange'。 | 686| callback | Callback<[AudioRingMode](js-apis-audio.md#audioringmode)> | 是 | 回调函数，返回变化后的铃音模式。 | 687 688**示例：** 689 690```ts 691audioManager.on('ringerModeChange', (ringerMode: audio.AudioRingMode) => { 692 console.info(`Updated ringermode: ${ringerMode}`); 693}); 694``` 695 696## AudioVolumeManager<sup>9+</sup> 697 698音量管理。在使用AudioVolumeManager的接口前，需要使用[getVolumeManager](js-apis-audio.md#getvolumemanager9)获取AudioVolumeManager实例。 699 700### getVolumeGroupInfos<sup>9+</sup> 701 702getVolumeGroupInfos(networkId: string, callback: AsyncCallback<VolumeGroupInfos\>\): void 703 704获取音量组信息列表，使用callback方式异步返回结果。 705 706**系统接口：** 该接口为系统接口 707 708**系统能力：** SystemCapability.Multimedia.Audio.Volume 709 710**参数：** 711 712| 参数名 | 类型 | 必填 | 说明 | 713| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 714| networkId | string | 是 | 设备的网络id。本地设备audio.LOCAL_NETWORK_ID。 | 715| callback | AsyncCallback<[VolumeGroupInfos](#volumegroupinfos9)> | 是 | 回调函数。当获取音量组信息列表成功，err为undefined，data为获取到的音量组信息列表；否则为错误对象。 | 716 717**示例：** 718```ts 719import { BusinessError } from '@kit.BasicServicesKit'; 720 721audioVolumeManager.getVolumeGroupInfos(audio.LOCAL_NETWORK_ID, (err: BusinessError, value: audio.VolumeGroupInfos) => { 722 if (err) { 723 console.error(`Failed to obtain the volume group infos list. ${err}`); 724 return; 725 } 726 console.info('Callback invoked to indicate that the volume group infos list is obtained.'); 727}); 728``` 729 730### getVolumeGroupInfos<sup>9+</sup> 731 732getVolumeGroupInfos(networkId: string\): Promise<VolumeGroupInfos\> 733 734获取音量组信息列表，使用Promise方式异步返回结果。 735 736**系统接口：** 该接口为系统接口 737 738**系统能力：** SystemCapability.Multimedia.Audio.Volume 739 740**参数：** 741 742| 参数名 | 类型 | 必填 | 说明 | 743| ---------- | ------------------| ---- | -------------------- | 744| networkId | string | 是 | 设备的网络id。本地设备audio.LOCAL_NETWORK_ID。 | 745 746**返回值：** 747 748| 类型 | 说明 | 749| ------------------- | ----------------------------- | 750| Promise<[VolumeGroupInfos](#volumegroupinfos9)> | Promise对象，返回音量组信息列表。 | 751 752**示例：** 753 754```ts 755async function getVolumeGroupInfos(){ 756 let volumegroupinfos: audio.VolumeGroupInfos = await audio.getAudioManager().getVolumeManager().getVolumeGroupInfos(audio.LOCAL_NETWORK_ID); 757 console.info('Promise returned to indicate that the volumeGroup list is obtained.'+JSON.stringify(volumegroupinfos)) 758} 759``` 760 761### getVolumeGroupInfosSync<sup>10+</sup> 762 763getVolumeGroupInfosSync(networkId: string\): VolumeGroupInfos 764 765获取音量组信息列表，同步返回结果。 766 767**系统接口：** 该接口为系统接口 768 769**系统能力：** SystemCapability.Multimedia.Audio.Volume 770 771**参数：** 772 773| 参数名 | 类型 | 必填 | 说明 | 774| ---------- | ------------------| ---- | -------------------- | 775| networkId | string | 是 | 设备的网络id。本地设备audio.LOCAL_NETWORK_ID。 | 776 777**返回值：** 778 779| 类型 | 说明 | 780| ------------------- | ----------------------------- | 781| [VolumeGroupInfos](#volumegroupinfos9) | 音量组信息列表。 | 782 783**错误码：** 784 785以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 786 787| 错误码ID | 错误信息 | 788| ------- | --------------------------------------------| 789| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 790| 6800101 | Parameter verification failed. | 791 792**示例：** 793 794```ts 795import { BusinessError } from '@kit.BasicServicesKit'; 796 797try { 798 let volumegroupinfos: audio.VolumeGroupInfos = audioVolumeManager.getVolumeGroupInfosSync(audio.LOCAL_NETWORK_ID); 799 console.info(`Indicate that the volumeGroup list is obtained. ${JSON.stringify(volumegroupinfos)}`); 800} catch (err) { 801 let error = err as BusinessError; 802 console.error(`Failed to obtain the volumeGroup list ${error}`); 803} 804``` 805 806## AudioVolumeGroupManager<sup>9+</sup> 807 808管理音频组音量。在调用AudioVolumeGroupManager的接口前，需要先通过 [getVolumeGroupManager](js-apis-audio.md#getvolumegroupmanager9) 创建实例。 809 810### setVolume<sup>9+</sup> 811 812setVolume(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback<void>): void 813 814设置指定流的音量，使用callback方式异步返回结果。 815 816**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 817 818仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 819 820**系统接口：** 该接口为系统接口 821 822**系统能力：** SystemCapability.Multimedia.Audio.Volume 823 824**参数：** 825 826| 参数名 | 类型 | 必填 | 说明 | 827| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 828| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 829| volume | number | 是 | 音量等级，可设置范围通过[getMinVolume](js-apis-audio.md#getminvolume9)和[getMaxVolume](js-apis-audio.md#getmaxvolume9)获取。 | 830| callback | AsyncCallback<void> | 是 | 回调函数。当设置指定流的音量成功，err为undefined，否则为错误对象。 | 831 832**示例：** 833 834```ts 835import { BusinessError } from '@kit.BasicServicesKit'; 836 837audioVolumeGroupManager.setVolume(audio.AudioVolumeType.MEDIA, 10, (err: BusinessError) => { 838 if (err) { 839 console.error(`Failed to set the volume. ${err}`); 840 return; 841 } 842 console.info('Callback invoked to indicate a successful volume setting.'); 843}); 844``` 845 846### setVolume<sup>9+</sup> 847 848setVolume(volumeType: AudioVolumeType, volume: number): Promise<void> 849 850设置指定流的音量，使用Promise方式异步返回结果。 851 852**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 853 854仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 855 856**系统接口：** 该接口为系统接口 857 858**系统能力：** SystemCapability.Multimedia.Audio.Volume 859 860**参数：** 861 862| 参数名 | 类型 | 必填 | 说明 | 863| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 864| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 865| volume | number | 是 | 音量等级，可设置范围通过[getMinVolume](js-apis-audio.md#getminvolume9)和[getMaxVolume](js-apis-audio.md#getmaxvolume9)获取。 | 866 867**返回值：** 868 869| 类型 | 说明 | 870| ------------------- | ----------------------------- | 871| Promise<void> | Promise对象，无返回结果。 | 872 873**示例：** 874 875```ts 876audioVolumeGroupManager.setVolume(audio.AudioVolumeType.MEDIA, 10).then(() => { 877 console.info('Promise returned to indicate a successful volume setting.'); 878}); 879``` 880 881### setVolumeWithFlag<sup>12+</sup> 882 883setVolumeWithFlag(volumeType: AudioVolumeType, volume: number, flags: number): Promise<void> 884 885设置指定流的音量，同时指定本次修改音量是否要显示系统音量条，使用Promise方式异步返回结果。 886 887**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 888 889仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 890 891**系统接口：** 该接口为系统接口 892 893**系统能力：** SystemCapability.Multimedia.Audio.Volume 894 895**参数：** 896 897| 参数名 | 类型 | 必填 | 说明 | 898| ---------- | ----------------------------------- | ---- |--------------------------------------| 899| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 900| volume | number | 是 | 音量等级，可设置范围通过[getMinVolume](js-apis-audio.md#getminvolume9)和[getMaxVolume](js-apis-audio.md#getmaxvolume9)获取。 | 901| flags | number | 是 | 是否需要显示系统音量条，0为不需要显示，1为需要显示。 | 902 903**返回值：** 904 905| 类型 | 说明 | 906| ------------------- | ----------------------------- | 907| Promise<void> | Promise对象，无返回结果。 | 908 909**错误码：** 910 911以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 912 913| 错误码ID | 错误信息 | 914| ------- | --------------------------------------------| 915| 201 | Permission denied. | 916| 202 | Not system App. | 917 918**示例：** 919 920```ts 921audioVolumeGroupManager.setVolumeWithFlag(audio.AudioVolumeType.MEDIA, 10, 1).then(() => { 922 console.info('Promise returned to indicate a successful volume setting.'); 923}); 924``` 925 926### mute<sup>9+</sup> 927 928mute(volumeType: AudioVolumeType, mute: boolean, callback: AsyncCallback<void>): void 929 930设置指定音量流静音，使用callback方式异步返回结果。 931 932**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 933 934仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 935 936**系统接口：** 该接口为系统接口 937 938**系统能力：** SystemCapability.Multimedia.Audio.Volume 939 940**参数：** 941 942| 参数名 | 类型 | 必填 | 说明 | 943| ---------- | ----------------------------------- | ---- | ------------------------------------- | 944| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 945| mute | boolean | 是 | 静音状态，true为静音，false为非静音。 | 946| callback | AsyncCallback<void> | 是 | 回调函数。当设置指定音量流静音成功，err为undefined，否则为错误对象。 | 947 948**示例：** 949 950```ts 951import { BusinessError } from '@kit.BasicServicesKit'; 952 953audioVolumeGroupManager.mute(audio.AudioVolumeType.MEDIA, true, (err: BusinessError) => { 954 if (err) { 955 console.error(`Failed to mute the stream. ${err}`); 956 return; 957 } 958 console.info('Callback invoked to indicate that the stream is muted.'); 959}); 960``` 961 962### mute<sup>9+</sup> 963 964mute(volumeType: AudioVolumeType, mute: boolean): Promise<void> 965 966设置指定音量流静音，使用Promise方式异步返回结果。 967 968**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 969 970仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 971 972**系统接口：** 该接口为系统接口 973 974**系统能力：** SystemCapability.Multimedia.Audio.Volume 975 976**参数：** 977 978| 参数名 | 类型 | 必填 | 说明 | 979| ---------- | ----------------------------------- | ---- | ------------------------------------- | 980| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 981| mute | boolean | 是 | 静音状态，true为静音，false为非静音。 | 982 983**返回值：** 984 985| 类型 | 说明 | 986| ------------------- | ----------------------------- | 987| Promise<void> | Promise对象，无返回结果。 | 988 989**示例：** 990 991```ts 992audioVolumeGroupManager.mute(audio.AudioVolumeType.MEDIA, true).then(() => { 993 console.info('Promise returned to indicate that the stream is muted.'); 994}); 995``` 996 997### setRingerMode<sup>9+</sup> 998 999setRingerMode(mode: AudioRingMode, callback: AsyncCallback<void>): void 1000 1001设置铃声模式，使用callback方式异步返回结果。 1002 1003**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1004 1005仅在静音和非静音状态切换时需要该权限。 1006 1007**系统接口：** 该接口为系统接口 1008 1009**系统能力：** SystemCapability.Multimedia.Audio.Volume 1010 1011**参数：** 1012 1013| 参数名 | 类型 | 必填 | 说明 | 1014| -------- | ------------------------------- | ---- | ------------------------ | 1015| mode | [AudioRingMode](js-apis-audio.md#audioringmode) | 是 | 音频铃声模式。 | 1016| callback | AsyncCallback<void> | 是 | 回调函数。当设置铃声模式成功，err为undefined，否则为错误对象。 | 1017 1018**示例：** 1019 1020```ts 1021import { BusinessError } from '@kit.BasicServicesKit'; 1022 1023audioVolumeGroupManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL, (err: BusinessError) => { 1024 if (err) { 1025 console.error(`Failed to set the ringer mode. ${err}`); 1026 return; 1027 } 1028 console.info('Callback invoked to indicate a successful setting of the ringer mode.'); 1029}); 1030``` 1031 1032### setRingerMode<sup>9+</sup> 1033 1034setRingerMode(mode: AudioRingMode): Promise<void> 1035 1036设置铃声模式，使用Promise方式异步返回结果。 1037 1038**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1039 1040仅在静音和非静音状态切换时需要该权限。 1041 1042**系统接口：** 该接口为系统接口 1043 1044**系统能力：** SystemCapability.Multimedia.Audio.Volume 1045 1046**参数：** 1047 1048| 参数名 | 类型 | 必填 | 说明 | 1049| ------ | ------------------------------- | ---- | -------------- | 1050| mode | [AudioRingMode](js-apis-audio.md#audioringmode) | 是 | 音频铃声模式。 | 1051 1052**返回值：** 1053 1054| 类型 | 说明 | 1055| ------------------- | ------------------------------- | 1056| Promise<void> | Promise对象，无返回结果。 | 1057 1058**示例：** 1059 1060```ts 1061audioVolumeGroupManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL).then(() => { 1062 console.info('Promise returned to indicate a successful setting of the ringer mode.'); 1063}); 1064``` 1065 1066### setMicMute<sup>11+</sup> 1067 1068setMicMute(mute: boolean): Promise<void> 1069 1070设置麦克风静音状态，使用Promise方式异步返回结果。 1071 1072**需要权限：** ohos.permission.MANAGE_AUDIO_CONFIG 1073 1074**系统接口：** 该接口为系统接口 1075 1076**系统能力：** SystemCapability.Multimedia.Audio.Volume 1077 1078**参数：** 1079 1080| 参数名 | 类型 | 必填 | 说明 | 1081| ------ | ------- | ---- | --------------------------------------------- | 1082| mute | boolean | 是 | 待设置的静音状态，true为静音，false为非静音。 | 1083 1084**返回值：** 1085 1086| 类型 | 说明 | 1087| ------------------- | ------------------------------- | 1088| Promise<void> | Promise对象，无返回结果。 | 1089 1090**错误码：** 1091 1092以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 1093 1094| 错误码ID | 错误信息 | 1095| ------- | --------------------------------------------| 1096| 201 | Permission denied. | 1097| 202 | Not system App. | 1098| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1099| 6800101 | Parameter verification failed. | 1100 1101**示例：** 1102 1103```ts 1104audioVolumeGroupManager.setMicMute(true).then(() => { 1105 console.info('Promise returned to indicate that the mic is muted.'); 1106}); 1107``` 1108 1109### adjustVolumeByStep<sup>10+</sup> 1110 1111adjustVolumeByStep(adjustType: VolumeAdjustType, callback: AsyncCallback<void>): void 1112 1113调节当前最高优先级的流的音量，使音量值按步长加或减，使用callback方式异步返回结果。 1114 1115**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1116 1117仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 1118 1119**系统接口：** 该接口为系统接口 1120 1121**系统能力：** SystemCapability.Multimedia.Audio.Volume 1122 1123**参数：** 1124 1125| 参数名 | 类型 | 必填 | 说明 | 1126| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1127| adjustType | [VolumeAdjustType](#volumeadjusttype10) | 是 | 音量调节方向。 | 1128| callback | AsyncCallback<void> | 是 | 回调函数。当调节当前最高优先级的流的音量成功，err为undefined，否则为错误对象。 | 1129 1130**错误码：** 1131 1132以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 1133 1134| 错误码ID | 错误信息 | 1135| ------- | --------------------------------------------| 1136| 201 | Permission denied. | 1137| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1138| 6800101 | Parameter verification failed. Return by callback. | 1139| 6800301 | System error. Return by callback. | 1140 1141**示例：** 1142 1143```ts 1144import { BusinessError } from '@kit.BasicServicesKit'; 1145 1146audioVolumeGroupManager.adjustVolumeByStep(audio.VolumeAdjustType.VOLUME_UP, (err: BusinessError) => { 1147 if (err) { 1148 console.error(`Failed to adjust the volume by step. ${err}`); 1149 return; 1150 } else { 1151 console.info('Success to adjust the volume by step.'); 1152 } 1153}); 1154``` 1155### adjustVolumeByStep<sup>10+</sup> 1156 1157adjustVolumeByStep(adjustType: VolumeAdjustType): Promise<void> 1158 1159单步设置当前最高优先级的流的音量，使用Promise方式异步返回结果。 1160 1161**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1162 1163仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 1164 1165**系统接口：** 该接口为系统接口 1166 1167**系统能力：** SystemCapability.Multimedia.Audio.Volume 1168 1169**参数：** 1170 1171| 参数名 | 类型 | 必填 | 说明 | 1172| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1173| adjustType | [VolumeAdjustType](#volumeadjusttype10) | 是 | 音量调节方向。 | 1174 1175**返回值：** 1176 1177| 类型 | 说明 | 1178| ------------------- | ----------------------------- | 1179| Promise<void> | Promise对象，无返回结果。 | 1180 1181**错误码：** 1182 1183以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 1184 1185| 错误码ID | 错误信息 | 1186| ------- | --------------------------------------------| 1187| 201 | Permission denied. | 1188| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1189| 6800101 | Parameter verification failed. Return by promise. | 1190| 6800301 | System error. Return by promise. | 1191 1192**示例：** 1193 1194```ts 1195import { BusinessError } from '@kit.BasicServicesKit'; 1196 1197audioVolumeGroupManager.adjustVolumeByStep(audio.VolumeAdjustType.VOLUME_UP).then(() => { 1198 console.info('Success to adjust the volume by step.'); 1199}).catch((error: BusinessError) => { 1200 console.error('Fail to adjust the volume by step.'); 1201}); 1202``` 1203 1204### adjustSystemVolumeByStep<sup>10+</sup> 1205 1206adjustSystemVolumeByStep(volumeType: AudioVolumeType, adjustType: VolumeAdjustType, callback: AsyncCallback<void>): void 1207 1208单步设置指定流的音量，使用callback方式异步返回结果。 1209 1210**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1211 1212仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 1213 1214**系统接口：** 该接口为系统接口 1215 1216**系统能力：** SystemCapability.Multimedia.Audio.Volume 1217 1218**参数：** 1219 1220| 参数名 | 类型 | 必填 | 说明 | 1221| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1222| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 1223| adjustType | [VolumeAdjustType](#volumeadjusttype10) | 是 | 音量调节方向。 | 1224| callback | AsyncCallback<void> | 是 | 回调函数。当单步设置指定流的音量成功，err为undefined，否则为错误对象。 | 1225 1226**错误码：** 1227 1228以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 1229 1230| 错误码ID | 错误信息 | 1231| ------- | --------------------------------------------| 1232| 201 | Permission denied. | 1233| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1234| 6800101 | Parameter verification failed. Return by callback. | 1235| 6800301 | System error. Return by callback. | 1236 1237**示例：** 1238 1239```ts 1240import { BusinessError } from '@kit.BasicServicesKit'; 1241 1242audioVolumeGroupManager.adjustSystemVolumeByStep(audio.AudioVolumeType.MEDIA, audio.VolumeAdjustType.VOLUME_UP, (err: BusinessError) => { 1243 if (err) { 1244 console.error(`Failed to adjust the system volume by step ${err}`); 1245 } else { 1246 console.info('Success to adjust the system volume by step.'); 1247 } 1248}); 1249``` 1250### adjustSystemVolumeByStep<sup>10+</sup> 1251 1252adjustSystemVolumeByStep(volumeType: AudioVolumeType, adjustType: VolumeAdjustType): Promise<void> 1253 1254单步设置指定流的音量，使用Promise方式异步返回结果。 1255 1256**需要权限：** ohos.permission.ACCESS_NOTIFICATION_POLICY 1257 1258仅设置铃声（即volumeType为AudioVolumeType.RINGTONE）在静音和非静音状态切换时需要该权限。 1259 1260**系统接口：** 该接口为系统接口 1261 1262**系统能力：** SystemCapability.Multimedia.Audio.Volume 1263 1264**参数：** 1265 1266| 参数名 | 类型 | 必填 | 说明 | 1267| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1268| volumeType | [AudioVolumeType](#audiovolumetype) | 是 | 音量流类型。 | 1269| adjustType | [VolumeAdjustType](#volumeadjusttype10) | 是 | 音量调节方向。 | 1270 1271**返回值：** 1272 1273| 类型 | 说明 | 1274| ------------------- | ----------------------------- | 1275| Promise<void> | Promise对象，无返回结果。 | 1276 1277**错误码：** 1278 1279以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 1280 1281| 错误码ID | 错误信息 | 1282| ------- | --------------------------------------------| 1283| 201 | Permission denied. | 1284| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1285| 6800101 | Parameter verification failed. Return by promise. | 1286| 6800301 | System error. Return by promise. | 1287 1288**示例：** 1289 1290```ts 1291import { BusinessError } from '@kit.BasicServicesKit'; 1292 1293audioVolumeGroupManager.adjustSystemVolumeByStep(audio.AudioVolumeType.MEDIA, audio.VolumeAdjustType.VOLUME_UP).then(() => { 1294 console.info('Success to adjust the system volume by step.'); 1295}).catch((error: BusinessError) => { 1296 console.error('Fail to adjust the system volume by step.'); 1297}); 1298``` 1299 1300## AudioRoutingManager<sup>9+</sup> 1301 1302音频路由管理。在使用AudioRoutingManager的接口前，需要使用[getRoutingManager](js-apis-audio.md#getroutingmanager9)获取AudioRoutingManager实例。 1303 1304### selectInputDevice<sup>9+</sup> 1305 1306selectInputDevice(inputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void 1307 1308选择音频输入设备，当前只能选择一个输入设备，使用callback方式异步返回结果。 1309 1310**系统接口：** 该接口为系统接口 1311 1312**系统能力：** SystemCapability.Multimedia.Audio.Device 1313 1314**参数：** 1315 1316| 参数名 | 类型 | 必填 | 说明 | 1317| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1318| inputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | 是 | 输入设备类。 | 1319| callback | AsyncCallback<void> | 是 | 回调函数。当选择音频输入设备成功，err为undefined，否则为错误对象。 | 1320 1321**示例：** 1322```ts 1323import { audio } from '@kit.AudioKit'; 1324import { BusinessError } from '@kit.BasicServicesKit'; 1325 1326let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1327 deviceRole : audio.DeviceRole.INPUT_DEVICE, 1328 deviceType : audio.DeviceType.MIC, 1329 id : 1, 1330 name : "", 1331 address : "", 1332 sampleRates : [44100], 1333 channelCounts : [2], 1334 channelMasks : [0], 1335 networkId : audio.LOCAL_NETWORK_ID, 1336 interruptGroupId : 1, 1337 volumeGroupId : 1, 1338 displayName : "", 1339}]; 1340 1341async function selectInputDevice(){ 1342 audioRoutingManager.selectInputDevice(inputAudioDeviceDescriptor, (err: BusinessError) => { 1343 if (err) { 1344 console.error(`Result ERROR: ${err}`); 1345 } else { 1346 console.info('Select input devices result callback: SUCCESS'); 1347 } 1348 }); 1349} 1350``` 1351 1352### selectInputDevice<sup>9+</sup> 1353 1354selectInputDevice(inputAudioDevices: AudioDeviceDescriptors): Promise<void> 1355 1356**系统接口：** 该接口为系统接口 1357 1358选择音频输入设备，当前只能选择一个输入设备，使用Promise方式异步返回结果。 1359 1360**系统能力：** SystemCapability.Multimedia.Audio.Device 1361 1362**参数：** 1363 1364| 参数名 | 类型 | 必填 | 说明 | 1365| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1366| inputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | 是 | 输入设备类。 | 1367 1368**返回值：** 1369 1370| 类型 | 说明 | 1371| --------------------- | --------------------------- | 1372| Promise<void> | Promise对象，无返回结果。 | 1373 1374**示例：** 1375 1376```ts 1377import { audio } from '@kit.AudioKit'; 1378import { BusinessError } from '@kit.BasicServicesKit'; 1379 1380let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1381 deviceRole : audio.DeviceRole.INPUT_DEVICE, 1382 deviceType : audio.DeviceType.MIC, 1383 id : 1, 1384 name : "", 1385 address : "", 1386 sampleRates : [44100], 1387 channelCounts : [2], 1388 channelMasks : [0], 1389 networkId : audio.LOCAL_NETWORK_ID, 1390 interruptGroupId : 1, 1391 volumeGroupId : 1, 1392 displayName : "", 1393}]; 1394 1395async function getRoutingManager(){ 1396 audioRoutingManager.selectInputDevice(inputAudioDeviceDescriptor).then(() => { 1397 console.info('Select input devices result promise: SUCCESS'); 1398 }).catch((err: BusinessError) => { 1399 console.error(`Result ERROR: ${err}`); 1400 }); 1401} 1402``` 1403 1404### selectOutputDevice<sup>9+</sup> 1405 1406selectOutputDevice(outputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void 1407 1408选择音频输出设备，当前只能选择一个输出设备，使用callback方式异步返回结果。 1409 1410**系统接口：** 该接口为系统接口 1411 1412**系统能力：** SystemCapability.Multimedia.Audio.Device 1413 1414**参数：** 1415 1416| 参数名 | 类型 | 必填 | 说明 | 1417| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1418| outputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | 是 | 输出设备类。 | 1419| callback | AsyncCallback<void> | 是 | 回调函数。当选择音频输出设备成功，err为undefined，否则为错误对象。 | 1420 1421**示例：** 1422```ts 1423import { audio } from '@kit.AudioKit'; 1424import { BusinessError } from '@kit.BasicServicesKit'; 1425 1426let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1427 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 1428 deviceType : audio.DeviceType.SPEAKER, 1429 id : 1, 1430 name : "", 1431 address : "", 1432 sampleRates : [44100], 1433 channelCounts : [2], 1434 channelMasks : [0], 1435 networkId : audio.LOCAL_NETWORK_ID, 1436 interruptGroupId : 1, 1437 volumeGroupId : 1, 1438 displayName : "", 1439}]; 1440 1441async function selectOutputDevice(){ 1442 audioRoutingManager.selectOutputDevice(outputAudioDeviceDescriptor, (err: BusinessError) => { 1443 if (err) { 1444 console.error(`Result ERROR: ${err}`); 1445 } else { 1446 console.info('Select output devices result callback: SUCCESS'); } 1447 }); 1448} 1449``` 1450 1451### selectOutputDevice<sup>9+</sup> 1452 1453selectOutputDevice(outputAudioDevices: AudioDeviceDescriptors): Promise<void> 1454 1455**系统接口：** 该接口为系统接口 1456 1457选择音频输出设备，当前只能选择一个输出设备，使用Promise方式异步返回结果。 1458 1459**系统能力：** SystemCapability.Multimedia.Audio.Device 1460 1461**参数：** 1462 1463| 参数名 | 类型 | 必填 | 说明 | 1464| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1465| outputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | 是 | 输出设备类。 | 1466 1467**返回值：** 1468 1469| 类型 | 说明 | 1470| --------------------- | --------------------------- | 1471| Promise<void> | Promise对象，无返回结果。 | 1472 1473**示例：** 1474 1475```ts 1476import { audio } from '@kit.AudioKit'; 1477import { BusinessError } from '@kit.BasicServicesKit'; 1478 1479let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1480 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 1481 deviceType : audio.DeviceType.SPEAKER, 1482 id : 1, 1483 name : "", 1484 address : "", 1485 sampleRates : [44100], 1486 channelCounts : [2], 1487 channelMasks : [0], 1488 networkId : audio.LOCAL_NETWORK_ID, 1489 interruptGroupId : 1, 1490 volumeGroupId : 1, 1491 displayName : "", 1492}]; 1493 1494async function selectOutputDevice(){ 1495 audioRoutingManager.selectOutputDevice(outputAudioDeviceDescriptor).then(() => { 1496 console.info('Select output devices result promise: SUCCESS'); 1497 }).catch((err: BusinessError) => { 1498 console.error(`Result ERROR: ${err}`); 1499 }); 1500} 1501``` 1502 1503### selectOutputDeviceByFilter<sup>9+</sup> 1504 1505selectOutputDeviceByFilter(filter: AudioRendererFilter, outputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void 1506 1507**系统接口：** 该接口为系统接口 1508 1509根据过滤条件，选择音频输出设备，当前只能选择一个输出设备，使用callback方式异步返回结果。 1510 1511**系统能力：** SystemCapability.Multimedia.Audio.Device 1512 1513**参数：** 1514 1515| 参数名 | 类型 | 必填 | 说明 | 1516| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1517| filter | [AudioRendererFilter](#audiorendererfilter9) | 是 | 过滤条件类。 | 1518| outputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | 是 | 输出设备类。 | 1519| callback | AsyncCallback<void> | 是 | 回调函数。当选择音频输出设备成功，err为undefined，否则为错误对象。 | 1520 1521**示例：** 1522```ts 1523import { audio } from '@kit.AudioKit'; 1524import { BusinessError } from '@kit.BasicServicesKit'; 1525 1526let outputAudioRendererFilter: audio.AudioRendererFilter = { 1527 uid : 20010041, 1528 rendererInfo : { 1529 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 1530 rendererFlags : 0 1531 }, 1532 rendererId : 0 1533}; 1534 1535let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1536 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 1537 deviceType : audio.DeviceType.SPEAKER, 1538 id : 1, 1539 name : "", 1540 address : "", 1541 sampleRates : [44100], 1542 channelCounts : [2], 1543 channelMasks : [0], 1544 networkId : audio.LOCAL_NETWORK_ID, 1545 interruptGroupId : 1, 1546 volumeGroupId : 1, 1547 displayName : "", 1548}]; 1549 1550async function selectOutputDeviceByFilter(){ 1551 audioRoutingManager.selectOutputDeviceByFilter(outputAudioRendererFilter, outputAudioDeviceDescriptor, (err: BusinessError) => { 1552 if (err) { 1553 console.error(`Result ERROR: ${err}`); 1554 } else { 1555 console.info('Select output devices by filter result callback: SUCCESS'); } 1556 }); 1557} 1558``` 1559 1560### selectOutputDeviceByFilter<sup>9+</sup> 1561 1562selectOutputDeviceByFilter(filter: AudioRendererFilter, outputAudioDevices: AudioDeviceDescriptors): Promise<void> 1563 1564**系统接口：** 该接口为系统接口 1565 1566根据过滤条件，选择音频输出设备，当前只能选择一个输出设备，使用Promise方式异步返回结果。 1567 1568**系统能力：** SystemCapability.Multimedia.Audio.Device 1569 1570**参数：** 1571 1572| 参数名 | 类型 | 必填 | 说明 | 1573| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 1574| filter | [AudioRendererFilter](#audiorendererfilter9) | 是 | 过滤条件类。 | 1575| outputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | 是 | 输出设备类。 | 1576 1577**返回值：** 1578 1579| 类型 | 说明 | 1580| --------------------- | --------------------------- | 1581| Promise<void> | Promise对象，无返回结果。 | 1582 1583**示例：** 1584 1585```ts 1586import { audio } from '@kit.AudioKit'; 1587import { BusinessError } from '@kit.BasicServicesKit'; 1588 1589let outputAudioRendererFilter: audio.AudioRendererFilter = { 1590 uid : 20010041, 1591 rendererInfo : { 1592 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 1593 rendererFlags : 0 1594 }, 1595 rendererId : 0 1596}; 1597 1598let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1599 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 1600 deviceType : audio.DeviceType.SPEAKER, 1601 id : 1, 1602 name : "", 1603 address : "", 1604 sampleRates : [44100], 1605 channelCounts : [2], 1606 channelMasks : [0], 1607 networkId : audio.LOCAL_NETWORK_ID, 1608 interruptGroupId : 1, 1609 volumeGroupId : 1, 1610 displayName : "", 1611}]; 1612 1613async function selectOutputDeviceByFilter(){ 1614 audioRoutingManager.selectOutputDeviceByFilter(outputAudioRendererFilter, outputAudioDeviceDescriptor).then(() => { 1615 console.info('Select output devices by filter result promise: SUCCESS'); 1616 }).catch((err: BusinessError) => { 1617 console.error(`Result ERROR: ${err}`); 1618 }) 1619} 1620``` 1621 1622## AudioRendererChangeInfo<sup>9+</sup> 1623 1624描述音频渲染器更改信息。 1625 1626**系统能力：** SystemCapability.Multimedia.Audio.Renderer 1627 1628| 名称 | 类型 | 可读 | 可写 | 说明 | 1629| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- | 1630| clientUid | number | 是 | 否 | 音频渲染器客户端应用程序的Uid。<br/>此接口为系统接口。 | 1631| rendererState | [AudioState](js-apis-audio.md#audiostate8) | 是 | 否 | 音频状态。<br/>此接口为系统接口。| 1632 1633## AudioCapturerChangeInfo<sup>9+</sup> 1634 1635描述音频采集器更改信息。 1636 1637**系统能力：** SystemCapability.Multimedia.Audio.Capturer 1638 1639| 名称 | 类型 | 可读 | 可写 | 说明 | 1640| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- | 1641| clientUid | number | 是 | 否 | 音频采集器客户端应用程序的Uid。<br/>此接口为系统接口。 | 1642| capturerState | [AudioState](js-apis-audio.md#audiostate8) | 是 | 否 | 音频状态。<br/>此接口为系统接口。| 1643 1644## AudioDeviceDescriptor 1645 1646描述音频设备。 1647 1648| 名称 | 类型 | 可读 | 可写 | 说明 | 1649| ----------------------------- | -------------------------- | ---- | ---- | ---------- | 1650| networkId<sup>9+</sup> | string | 是 | 否 | 设备组网的ID。<br/>此接口为系统接口。 <br> **系统能力：** SystemCapability.Multimedia.Audio.Device| 1651| interruptGroupId<sup>9+</sup> | number | 是 | 否 | 设备所处的焦点组ID。<br/>此接口为系统接口。 <br> **系统能力：** SystemCapability.Multimedia.Audio.Device| 1652| volumeGroupId<sup>9+</sup> | number | 是 | 否 | 设备所处的音量组ID。<br/>此接口为系统接口。 <br> **系统能力：** SystemCapability.Multimedia.Audio.Device| 1653 1654## AudioRendererFilter<sup>9+</sup> 1655 1656过滤条件类。在调用selectOutputDeviceByFilter接口前，需要先创建AudioRendererFilter实例。 1657 1658**系统接口：** 该接口为系统接口 1659 1660| 名称 | 类型 | 必填 | 说明 | 1661| -------------| ---------------------------------------- | ---- | -------------- | 1662| uid | number | 否 | 表示应用ID。<br> **系统能力：** SystemCapability.Multimedia.Audio.Core| 1663| rendererInfo | [AudioRendererInfo](js-apis-audio.md#audiorendererinfo8) | 否 | 表示渲染器信息。<br> **系统能力：** SystemCapability.Multimedia.Audio.Renderer| 1664| rendererId | number | 否 | 音频流唯一id。<br> **系统能力：** SystemCapability.Multimedia.Audio.Renderer| 1665 1666**示例：** 1667 1668```ts 1669import { audio } from '@kit.AudioKit'; 1670 1671let outputAudioRendererFilter: audio.AudioRendererFilter = { 1672 uid : 20010041, 1673 rendererInfo : { 1674 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 1675 rendererFlags : 0 1676 }, 1677 rendererId : 0 1678}; 1679``` 1680 1681## AudioSpatialEnabledStateForDevice<sup>12+</sup> 1682 1683监听设备空间音频开关状态。 1684 1685**系统接口**：此接口为系统接口。 1686 1687**系统能力**：SystemCapability.Multimedia.Audio 1688 1689| 参数名 | 类型 | 必填 | 说明 | 1690| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 1691| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | 是 | 指定设备的描述。 | 1692| enabled | boolean | 是 | 表示开启/关闭空间音频渲染或头动。true为开启，false为关闭。 | 1693 1694## AudioSpatializationManager<sup>11+</sup> 1695 1696空间音频管理。在使用AudioSpatializationManager的接口前，需要使用[getSpatializationManager](#getspatializationmanager11)获取AudioSpatializationManager实例。 1697 1698### isSpatializationSupported<sup>11+</sup> 1699 1700isSpatializationSupported(): boolean 1701 1702获取系统是否支持空间音频，同步返回结果。 1703 1704**系统接口：** 该接口为系统接口 1705 1706**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 1707 1708**返回值：** 1709 1710| 类型 | 说明 | 1711| ---------------------- | ------------------------------------------------------------ | 1712| boolean | 返回系统是否支持空间音频，true为支持，false为不支持。 | 1713 1714**错误码：** 1715 1716以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 1717 1718| 错误码ID | 错误信息 | 1719| ------- | --------------------------------------------| 1720| 202 | Not system App. | 1721 1722**示例：** 1723 1724```ts 1725import { audio } from '@kit.AudioKit'; 1726import { BusinessError } from '@kit.BasicServicesKit'; 1727try { 1728 let isSpatializationSupported: boolean = audioSpatializationManager.isSpatializationSupported(); 1729 console.info(`AudioSpatializationManager isSpatializationSupported: ${isSpatializationSupported}`); 1730} catch (err) { 1731 let error = err as BusinessError; 1732 console.error(`ERROR: ${error}`); 1733} 1734``` 1735 1736### isSpatializationSupportedForDevice<sup>11+</sup> 1737 1738isSpatializationSupportedForDevice(deviceDescriptor: AudioDeviceDescriptor): boolean 1739 1740获取指定设备是否支持空间音频，同步返回结果。 1741 1742**系统接口：** 该接口为系统接口 1743 1744**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 1745 1746**参数：** 1747 1748| 参数名 | 类型 | 必填 | 说明 | 1749| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 1750| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | 是 | 指定设备的描述。 | 1751 1752**返回值：** 1753 1754| 类型 | 说明 | 1755| ---------------------- | ------------------------------------------------------------ | 1756| boolean | 返回指定设备是否支持空间音频，true为支持，false为不支持。 | 1757 1758**错误码：** 1759 1760以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 1761 1762| 错误码ID | 错误信息 | 1763| ------- | --------------------------------------------| 1764| 202 | Not system App. | 1765| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1766| 6800101 | Parameter verification failed. | 1767 1768**示例：** 1769 1770```ts 1771import { audio } from '@kit.AudioKit'; 1772import { BusinessError } from '@kit.BasicServicesKit'; 1773 1774let deviceDescriptor: audio.AudioDeviceDescriptor = { 1775 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 1776 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 1777 id : 1, 1778 name : "", 1779 address : "123", 1780 sampleRates : [44100], 1781 channelCounts : [2], 1782 channelMasks : [0], 1783 networkId : audio.LOCAL_NETWORK_ID, 1784 interruptGroupId : 1, 1785 volumeGroupId : 1, 1786 displayName : "" 1787}; 1788 1789try { 1790 let isSpatializationSupportedForDevice: boolean = audioSpatializationManager.isSpatializationSupportedForDevice(deviceDescriptor); 1791 console.info(`AudioSpatializationManager isSpatializationSupportedForDevice: ${isSpatializationSupportedForDevice}`); 1792} catch (err) { 1793 let error = err as BusinessError; 1794 console.error(`ERROR: ${error}`); 1795} 1796``` 1797 1798### isHeadTrackingSupported<sup>11+</sup> 1799 1800isHeadTrackingSupported(): boolean 1801 1802获取系统是否支持头动跟踪，同步返回结果。 1803 1804**系统接口：** 该接口为系统接口 1805 1806**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 1807 1808**返回值：** 1809 1810| 类型 | 说明 | 1811| ---------------------- | ------------------------------------------------------------ | 1812| boolean | 返回系统是否支持头动跟踪，true为支持，false为不支持。 | 1813 1814**错误码：** 1815 1816以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 1817 1818| 错误码ID | 错误信息 | 1819| ------- | --------------------------------------------| 1820| 202 | Not system App. | 1821 1822**示例：** 1823 1824```ts 1825import { audio } from '@kit.AudioKit'; 1826import { BusinessError } from '@kit.BasicServicesKit'; 1827 1828try { 1829 let isHeadTrackingSupported: boolean = audioSpatializationManager.isHeadTrackingSupported(); 1830 console.info(`AudioSpatializationManager isHeadTrackingSupported: ${isHeadTrackingSupported}`); 1831} catch (err) { 1832 let error = err as BusinessError; 1833 console.error(`ERROR: ${error}`); 1834} 1835``` 1836 1837### isHeadTrackingSupportedForDevice<sup>11+</sup> 1838 1839isHeadTrackingSupportedForDevice(deviceDescriptor: AudioDeviceDescriptor): boolean 1840 1841获取指定设备是否支持头动跟踪，同步返回结果。 1842 1843**系统接口：** 该接口为系统接口 1844 1845**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 1846 1847**参数：** 1848 1849| 参数名 | 类型 | 必填 | 说明 | 1850| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 1851| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | 是 | 指定设备的描述。 | 1852 1853**返回值：** 1854 1855| 类型 | 说明 | 1856| ---------------------- | ------------------------------------------------------------ | 1857| boolean | 返回指定设备是否支持头动跟踪，true为支持，false为不支持。 | 1858 1859**错误码：** 1860 1861以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 1862 1863| 错误码ID | 错误信息 | 1864| ------- | --------------------------------------------| 1865| 202 | Not system App. | 1866| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1867| 6800101 | Parameter verification failed. | 1868 1869**示例：** 1870 1871```ts 1872import { audio } from '@kit.AudioKit'; 1873import { BusinessError } from '@kit.BasicServicesKit'; 1874 1875let deviceDescriptor: audio.AudioDeviceDescriptor = { 1876 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 1877 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 1878 id : 1, 1879 name : "", 1880 address : "123", 1881 sampleRates : [44100], 1882 channelCounts : [2], 1883 channelMasks : [0], 1884 networkId : audio.LOCAL_NETWORK_ID, 1885 interruptGroupId : 1, 1886 volumeGroupId : 1, 1887 displayName : "" 1888}; 1889 1890try { 1891 let isHeadTrackingSupportedForDevice: boolean = audioSpatializationManager.isHeadTrackingSupportedForDevice(deviceDescriptor); 1892 console.info(`AudioSpatializationManager isHeadTrackingSupportedForDevice: ${isHeadTrackingSupportedForDevice}`); 1893} catch (err) { 1894 let error = err as BusinessError; 1895 console.error(`ERROR: ${error}`); 1896} 1897``` 1898 1899### setSpatializationEnabled<sup>(deprecated)</sup> 1900 1901setSpatializationEnabled(enable: boolean, callback: AsyncCallback<void>): void 1902 1903根据输入指令，开启/关闭空间音频渲染效果，使用callback方式异步返回结果。 1904 1905> **说明：** 1906> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\<void>](#setspatializationenabled12)替代。 1907 1908**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 1909 1910**系统接口：** 该接口为系统接口 1911 1912**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 1913 1914**参数：** 1915 1916| 参数名 | 类型 | 必填 | 说明 | 1917| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1918| enable | boolean | 是 | 表示开启/关闭空间音频渲染。true为开启，false为关闭。 | 1919| callback | AsyncCallback<void> | 是 | AsyncCallback对象，无返回结果。 | 1920 1921**错误码：** 1922 1923以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 1924 1925| 错误码ID | 错误信息 | 1926| ------- | --------------------------------------------| 1927| 201 | Permission denied. Return by callback. | 1928| 202 | Not system App. | 1929| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1930| 6800101 | Parameter verification failed. | 1931 1932**示例：** 1933```ts 1934import { audio } from '@kit.AudioKit'; 1935import { BusinessError } from '@kit.BasicServicesKit'; 1936 1937let enable: boolean = true; 1938 1939audioSpatializationManager.setSpatializationEnabled(enable, (err: BusinessError) => { 1940 if (err) { 1941 console.error(`Result ERROR: ${err}`); 1942 } else { 1943 console.info(`setSpatializationEnabled success`); 1944 } 1945}); 1946``` 1947 1948### setSpatializationEnabled<sup>(deprecated)</sup> 1949 1950setSpatializationEnabled(enable: boolean): Promise<void> 1951 1952根据输入指令，开启/关闭空间音频渲染效果，使用Promise方式异步返回结果。 1953 1954> **说明：** 1955> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\<void>](#setspatializationenabled12)替代。 1956 1957**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 1958 1959**系统接口：** 该接口为系统接口 1960 1961**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 1962 1963**参数：** 1964 1965| 参数名 | 类型 | 必填 | 说明 | 1966| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 1967| enable | boolean | 是 | 表示开启/关闭空间音频渲染。true为开启，false为关闭。 | 1968 1969**返回值：** 1970 1971| 类型 | 说明 | 1972| --------------------- | --------------------------- | 1973| Promise<void> | Promise对象，无返回结果。 | 1974 1975**错误码：** 1976 1977以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 1978 1979| 错误码ID | 错误信息 | 1980| ------- | --------------------------------------------| 1981| 201 | Permission denied. Return by promise. | 1982| 202 | Not system App. | 1983| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1984 1985**示例：** 1986 1987```ts 1988import { audio } from '@kit.AudioKit'; 1989import { BusinessError } from '@kit.BasicServicesKit'; 1990 1991let enable: boolean = true; 1992 1993audioSpatializationManager.setSpatializationEnabled(enable).then(() => { 1994 console.info(`setSpatializationEnabled success`); 1995}).catch((err: BusinessError) => { 1996 console.error(`Result ERROR: ${err}`); 1997}); 1998``` 1999### setSpatializationEnabled<sup>12+</sup> 2000 2001setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise<void> 2002 2003根据输入指令，开启/关闭指定设备的空间音频渲染效果，使用Promise方式异步返回结果。 2004 2005**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2006 2007**系统接口：** 该接口为系统接口 2008 2009**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2010 2011**参数：** 2012 2013| 参数名 | 类型 | 必填 | 说明 | 2014| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 2015| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | 是 | 指定设备的描述。 | 2016| enabled | boolean | 是 | 表示开启/关闭空间音频渲染。true为开启，false为关闭。 | 2017 2018**返回值：** 2019 2020| 类型 | 说明 | 2021| --------------------- | --------------------------- | 2022| Promise<void> | Promise对象，无返回结果。 | 2023 2024**错误码：** 2025 2026以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2027 2028| 错误码ID | 错误信息 | 2029| ------- | --------------------------------------------| 2030| 201 | Permission denied. Return by promise. | 2031| 202 | Not system App. | 2032| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2033| 6800101 | Parameter verification failed. | 2034 2035 2036**示例：** 2037 2038```ts 2039import { audio } from '@kit.AudioKit'; 2040import { BusinessError } from '@kit.BasicServicesKit'; 2041 2042let deviceDescriptor: audio.AudioDeviceDescriptor = { 2043 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2044 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2045 id : 1, 2046 name : "", 2047 address : "123", 2048 sampleRates : [44100], 2049 channelCounts : [2], 2050 channelMasks : [0], 2051 networkId : audio.LOCAL_NETWORK_ID, 2052 interruptGroupId : 1, 2053 volumeGroupId : 1, 2054 displayName : "" 2055}; 2056let enabled: boolean = true; 2057 2058audioSpatializationManager.setSpatializationEnabled(deviceDescriptor, enabled).then(() => { 2059 console.info(`setSpatializationEnabled success`); 2060}).catch((err: BusinessError) => { 2061 console.error(`Result ERROR: ${err}`); 2062}); 2063``` 2064 2065### isSpatializationEnabled<sup>(deprecated)</sup> 2066 2067isSpatializationEnabled(): boolean 2068 2069获取空间音频渲染是否开启，同步返回结果。 2070 2071> **说明：** 2072> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[isSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean](#isspatializationenabled12)替代。 2073 2074**系统接口：** 该接口为系统接口 2075 2076**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2077 2078**返回值：** 2079 2080| 类型 | 说明 | 2081| ---------------------- | ------------------------------------------------------------ | 2082| boolean | 返回空间音频渲染是否开启，true为开启，false为未开启。 | 2083 2084**错误码：** 2085 2086以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2087 2088| 错误码ID | 错误信息 | 2089| ------- | --------------------------------------------| 2090| 202 | Not system App. | 2091 2092**示例：** 2093 2094```ts 2095import { audio } from '@kit.AudioKit'; 2096import { BusinessError } from '@kit.BasicServicesKit'; 2097 2098try { 2099 let isSpatializationEnabled: boolean = audioSpatializationManager.isSpatializationEnabled(); 2100 console.info(`AudioSpatializationManager isSpatializationEnabled: ${isSpatializationEnabled}`); 2101} catch (err) { 2102 let error = err as BusinessError; 2103 console.error(`ERROR: ${error}`); 2104} 2105``` 2106 2107### isSpatializationEnabled<sup>12+</sup> 2108 2109isSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean 2110 2111获取指定设备的空间音频渲染是否开启，同步返回结果。 2112 2113**系统接口：** 该接口为系统接口 2114 2115**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2116 2117**参数：** 2118 2119| 参数名 | 类型 | 必填 | 说明 | 2120| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 2121| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | 是 | 指定设备的描述。 | 2122 2123**返回值：** 2124 2125| 类型 | 说明 | 2126| ---------------------- | ------------------------------------------------------------ | 2127| boolean | 返回指定设备的空间音频渲染是否开启，true为开启，false为未开启。 | 2128 2129**错误码：** 2130 2131以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2132 2133| 错误码ID | 错误信息 | 2134| ------- | --------------------------------------------| 2135| 202 | Not system App. | 2136| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2137| 6800101 | Parameter verification failed. | 2138 2139**示例：** 2140 2141```ts 2142import { audio } from '@kit.AudioKit'; 2143import { BusinessError } from '@kit.BasicServicesKit'; 2144 2145let deviceDescriptor: audio.AudioDeviceDescriptor = { 2146 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2147 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2148 id : 1, 2149 name : "", 2150 address : "123", 2151 sampleRates : [44100], 2152 channelCounts : [2], 2153 channelMasks : [0], 2154 networkId : audio.LOCAL_NETWORK_ID, 2155 interruptGroupId : 1, 2156 volumeGroupId : 1, 2157 displayName : "" 2158}; 2159 2160try { 2161 let isSpatializationEnabled: boolean = audioSpatializationManager.isSpatializationEnabled(deviceDescriptor); 2162 console.info(`AudioSpatializationManager isSpatializationEnabled: ${isSpatializationEnabled}`); 2163} catch (err) { 2164 let error = err as BusinessError; 2165 console.error(`ERROR: ${error}`); 2166} 2167``` 2168 2169### on('spatializationEnabledChange')<sup>(deprecated)</sup> 2170 2171on(type: 'spatializationEnabledChange', callback: Callback<boolean\>): void 2172 2173监听空间音频渲染开关状态变化事件（当空间音频渲染开关状态发生变化时触发），使用callback方式返回结果。 2174 2175> **说明：** 2176> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[on(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void](#onspatializationenabledchangeforanydevice12)替代。 2177 2178**系统接口：** 该接口为系统接口 2179 2180**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2181 2182**参数：** 2183 2184| 参数名 | 类型 | 必填 | 说明 | 2185| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------| 2186| type | string | 是 | 监听事件，固定为：'spatializationEnabledChange'。 | 2187| callback | Callback<boolean\> | 是 | 回调函数，返回空间音频渲染开关状态，true为打开，false为关闭。 | 2188 2189**错误码：** 2190 2191以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2192 2193| 错误码ID | 错误信息 | 2194| ------- | --------------------------------------------| 2195| 202 | Not system App. | 2196| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2197| 6800101 | Parameter verification failed. | 2198 2199**示例：** 2200 2201```ts 2202import { audio } from '@kit.AudioKit'; 2203 2204audioSpatializationManager.on('spatializationEnabledChange', (isSpatializationEnabled: boolean) => { 2205 console.info(`isSpatializationEnabled: ${isSpatializationEnabled}`); 2206}); 2207``` 2208 2209### on('spatializationEnabledChangeForAnyDevice')<sup>12+</sup> 2210 2211on(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void 2212 2213监听空间音频渲染开关状态变化事件（当空间音频渲染开关状态发生变化时触发），使用callback方式返回结果。 2214 2215**系统接口：** 该接口为系统接口 2216 2217**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2218 2219**参数：** 2220 2221| 参数名 | 类型 | 必填 | 说明 | 2222| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------| 2223| type | string | 是 | 监听事件，固定为：'spatializationEnabledChangeForAnyDevice'。 | 2224| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | 是 | Callback对象，返回设备信息和空间音频渲染开关状态 | 2225 2226**错误码：** 2227 2228以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2229 2230| 错误码ID | 错误信息 | 2231| ------- | --------------------------------------------| 2232| 202 | Not system App. | 2233| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2234| 6800101 | Parameter verification failed. | 2235 2236**示例：** 2237 2238```ts 2239import { audio } from '@kit.AudioKit'; 2240 2241audioSpatializationManager.on('spatializationEnabledChangeForAnyDevice', (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 2242 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 2243 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 2244}); 2245``` 2246 2247### off('spatializationEnabledChange')<sup>(deprecated)</sup> 2248 2249off(type: 'spatializationEnabledChange', callback?: Callback<boolean\>): void 2250 2251取消监听空间音频渲染开关状态变化事件，使用callback方式返回结果。 2252 2253> **说明：** 2254> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[off(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void](#offspatializationenabledchangeforanydevice12)替代。 2255 2256**系统接口：** 该接口为系统接口 2257 2258**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2259 2260**参数：** 2261 2262| 参数名 | 类型 | 必填 | 说明 | 2263| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 2264| type | string | 是 | 监听事件，固定为：'spatializationEnabledChange'。 | 2265| callback | Callback<boolean\> | 否 | 回调函数，返回空间音频渲染开关状态，true为打开，false为关闭。 | 2266 2267**错误码：** 2268 2269以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2270 2271| 错误码ID | 错误信息 | 2272| ------- | --------------------------------------------| 2273| 202 | Not system App. | 2274| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2275| 6800101 | Parameter verification failed. | 2276 2277**示例：** 2278 2279```ts 2280// 取消该事件的所有监听 2281audioSpatializationManager.off('spatializationEnabledChange'); 2282 2283// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听 2284let spatializationEnabledChangeCallback = (isSpatializationEnabled: boolean) => { 2285 console.info(`isSpatializationEnabled: ${isSpatializationEnabled}`); 2286}; 2287 2288audioSpatializationManager.on('spatializationEnabledChange', spatializationEnabledChangeCallback); 2289 2290audioSpatializationManager.off('spatializationEnabledChange', spatializationEnabledChangeCallback); 2291``` 2292 2293### off('spatializationEnabledChangeForAnyDevice')<sup>12+</sup> 2294 2295off(type: 'spatializationEnabledChangeForAnyDevice', callback?: Callback<AudioSpatialEnabledStateForDevice\>): void 2296 2297取消监听空间音频渲染开关状态变化事件，使用callback方式返回结果。 2298 2299**系统接口：** 该接口为系统接口 2300 2301**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2302 2303**参数：** 2304 2305| 参数名 | 类型 | 必填 | 说明 | 2306| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------| 2307| type | string | 是 | 监听事件，固定为：'spatializationEnabledChangeForAnyDevice'。 | 2308| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | 是 | 回调函数，返回设备信息和空间音频渲染开关状态。 | 2309 2310**错误码：** 2311 2312以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2313 2314| 错误码ID | 错误信息 | 2315| ------- | --------------------------------------------| 2316| 202 | Not system App. | 2317| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2318| 6800101 | Parameter verification failed. | 2319 2320**示例：** 2321 2322```ts 2323import { audio } from '@kit.AudioKit'; 2324 2325// 取消该事件的所有监听 2326audioSpatializationManager.off('spatializationEnabledChangeForAnyDevice'); 2327 2328// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听 2329let spatializationEnabledChangeForAnyDeviceCallback = (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 2330 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 2331 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 2332}; 2333 2334audioSpatializationManager.on('spatializationEnabledChangeForAnyDevice', spatializationEnabledChangeForAnyDeviceCallback); 2335 2336audioSpatializationManager.off('spatializationEnabledChangeForAnyDevice', spatializationEnabledChangeForAnyDeviceCallback); 2337``` 2338 2339### setHeadTrackingEnabled<sup>(deprecated)</sup> 2340 2341setHeadTrackingEnabled(enable: boolean, callback: AsyncCallback<void>): void 2342 2343根据输入指令，开启/关闭头动跟踪效果，使用callback方式异步返回结果。 2344 2345> **说明：** 2346> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[setHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\<void>](#setheadtrackingenabled12)替代。 2347 2348**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2349 2350**系统接口：** 该接口为系统接口 2351 2352**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2353 2354**参数：** 2355 2356| 参数名 | 类型 | 必填 | 说明 | 2357| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 2358| enable | boolean | 是 | 表示开启/关闭头动跟踪。true为开启，false为关闭。 | 2359| callback | AsyncCallback<void> | 是 | AsyncCallback对象，无返回结果。 | 2360 2361**错误码：** 2362 2363以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2364 2365| 错误码ID | 错误信息 | 2366| ------- | --------------------------------------------| 2367| 201 | Permission denied. Return by callback. | 2368| 202 | Not system App. | 2369| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2370| 6800101 | Parameter verification failed. | 2371 2372**示例：** 2373```ts 2374import { audio } from '@kit.AudioKit'; 2375import { BusinessError } from '@kit.BasicServicesKit'; 2376 2377let enable: boolean = true; 2378 2379audioSpatializationManager.setHeadTrackingEnabled(enable, (err: BusinessError) => { 2380 if (err) { 2381 console.error(`Result ERROR: ${err}`); 2382 } else { 2383 console.info(`setHeadTrackingEnabled success`); 2384 } 2385}); 2386``` 2387 2388### setHeadTrackingEnabled<sup>(deprecated)</sup> 2389 2390setHeadTrackingEnabled(enable: boolean): Promise<void> 2391 2392根据输入指令，开启/关闭头动跟踪效果，使用Promise方式异步返回结果。 2393 2394> **说明：** 2395> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[setHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\<void>](#setheadtrackingenabled12)替代。 2396 2397**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2398 2399**系统接口：** 该接口为系统接口 2400 2401**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2402 2403**参数：** 2404 2405| 参数名 | 类型 | 必填 | 说明 | 2406| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 2407| enable | boolean | 是 | 表示开启/关闭头动跟踪。true为开启，false为关闭。 | 2408 2409**返回值：** 2410 2411| 类型 | 说明 | 2412| --------------------- | --------------------------- | 2413| Promise<void> | Promise对象，无返回结果。 | 2414 2415**错误码：** 2416 2417以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2418 2419| 错误码ID | 错误信息 | 2420| ------- | --------------------------------------------| 2421| 201 | Permission denied. Return by promise. | 2422| 202 | Not system App. | 2423| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2424 2425**示例：** 2426 2427```ts 2428import { audio } from '@kit.AudioKit'; 2429import { BusinessError } from '@kit.BasicServicesKit'; 2430 2431let enable: boolean = true; 2432 2433audioSpatializationManager.setHeadTrackingEnabled(enable).then(() => { 2434 console.info(`setHeadTrackingEnabled success`); 2435}).catch((err: BusinessError) => { 2436 console.error(`Result ERROR: ${err}`); 2437}); 2438``` 2439 2440### setHeadTrackingEnabled<sup>12+</sup> 2441 2442setHeadTrackingEnabled(enable: boolean): Promise<void> 2443 2444根据输入指令，开启/关闭指定设备的头动跟踪效果，使用Promise方式异步返回结果。 2445 2446**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2447 2448**系统接口：** 该接口为系统接口 2449 2450**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2451 2452**参数：** 2453 2454| 参数名 | 类型 | 必填 | 说明 | 2455| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 2456| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | 是 | 指定设备的描述。 | 2457| enable | boolean | 是 | 表示开启/关闭头动跟踪。true为开启，false为关闭。 | 2458 2459**返回值：** 2460 2461| 类型 | 说明 | 2462| --------------------- | --------------------------- | 2463| Promise<void> | Promise对象，无返回结果。 | 2464 2465**错误码：** 2466 2467以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2468 2469| 错误码ID | 错误信息 | 2470| ------- | --------------------------------------------| 2471| 201 | Permission denied. Return by promise. | 2472| 202 | Not system App. | 2473| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2474| 6800101 | Parameter verification failed. | 2475 2476**示例：** 2477 2478```ts 2479import { audio } from '@kit.AudioKit'; 2480import { BusinessError } from '@kit.BasicServicesKit'; 2481 2482let deviceDescriptor: audio.AudioDeviceDescriptor = { 2483 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2484 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2485 id : 1, 2486 name : "", 2487 address : "123", 2488 sampleRates : [44100], 2489 channelCounts : [2], 2490 channelMasks : [0], 2491 networkId : audio.LOCAL_NETWORK_ID, 2492 interruptGroupId : 1, 2493 volumeGroupId : 1, 2494 displayName : "" 2495}; 2496let enable: boolean = true; 2497 2498audioSpatializationManager.setHeadTrackingEnabled(deviceDescriptor, enable).then(() => { 2499 console.info(`setHeadTrackingEnabled success`); 2500}).catch((err: BusinessError) => { 2501 console.error(`Result ERROR: ${err}`); 2502}); 2503``` 2504 2505### isHeadTrackingEnabled<sup>(deprecated)</sup> 2506 2507isHeadTrackingEnabled(): boolean 2508 2509获取头动跟踪是否开启，同步返回结果。 2510 2511> **说明：** 2512> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[isHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean](#isheadtrackingenabled12)替代。 2513 2514**系统接口：** 该接口为系统接口 2515 2516**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2517 2518**返回值：** 2519 2520| 类型 | 说明 | 2521| ---------------------- | ------------------------------------------------------------ | 2522| boolean | 返回头动跟踪是否开启，true为开启，false为未开启。 | 2523 2524**错误码：** 2525 2526以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2527 2528| 错误码ID | 错误信息 | 2529| ------- | --------------------------------------------| 2530| 202 | Not system App. | 2531 2532**示例：** 2533 2534```ts 2535import { audio } from '@kit.AudioKit'; 2536import { BusinessError } from '@kit.BasicServicesKit'; 2537 2538try { 2539 let isHeadTrackingEnabled: boolean = audioSpatializationManager.isHeadTrackingEnabled(); 2540 console.info(`AudioSpatializationManager isHeadTrackingEnabled: ${isHeadTrackingEnabled}`); 2541} catch (err) { 2542 let error = err as BusinessError; 2543 console.error(`ERROR: ${error}`); 2544} 2545``` 2546 2547### isHeadTrackingEnabled<sup>12+</sup> 2548 2549isHeadTrackingEnabled(): boolean 2550 2551获取指定设备的头动跟踪是否开启，同步返回结果。 2552 2553**系统接口：** 该接口为系统接口 2554 2555**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2556 2557**参数：** 2558 2559| 参数名 | 类型 | 必填 | 说明 | 2560| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 2561| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | 是 | 指定设备的描述。 | 2562 2563**返回值：** 2564 2565| 类型 | 说明 | 2566| ---------------------- | ------------------------------------------------------------ | 2567| boolean | 返回指定设备的头动跟踪是否开启，true为开启，false为未开启。 | 2568 2569**错误码：** 2570 2571以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2572 2573| 错误码ID | 错误信息 | 2574| ------- | --------------------------------------------| 2575| 202 | Not system App. | 2576| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2577| 6800101 | Parameter verification failed. | 2578 2579**示例：** 2580 2581```ts 2582import { audio } from '@kit.AudioKit'; 2583import { BusinessError } from '@kit.BasicServicesKit'; 2584 2585let deviceDescriptor: audio.AudioDeviceDescriptor = { 2586 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2587 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2588 id : 1, 2589 name : "", 2590 address : "123", 2591 sampleRates : [44100], 2592 channelCounts : [2], 2593 channelMasks : [0], 2594 networkId : audio.LOCAL_NETWORK_ID, 2595 interruptGroupId : 1, 2596 volumeGroupId : 1, 2597 displayName : "" 2598}; 2599 2600try { 2601 let isHeadTrackingEnabled: boolean = audioSpatializationManager.isHeadTrackingEnabled(deviceDescriptor); 2602 console.info(`AudioSpatializationManager isHeadTrackingEnabled: ${isHeadTrackingEnabled}`); 2603} catch (err) { 2604 let error = err as BusinessError; 2605 console.error(`ERROR: ${error}`); 2606} 2607``` 2608 2609### on('headTrackingEnabledChange')<sup>(deprecated)</sup> 2610 2611on(type: 'headTrackingEnabledChange', callback: Callback<boolean\>): void 2612 2613监听头动跟踪开关状态变化事件（当动跟踪开关状态发生变化时触发），使用callback方式返回结果。 2614 2615> **说明：** 2616> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[on(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void](#onheadtrackingenabledchangeforanydevice12)替代。 2617 2618**系统接口：** 该接口为系统接口 2619 2620**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2621 2622**参数：** 2623 2624| 参数名 | 类型 | 必填 | 说明 | 2625| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 2626| type | string | 是 | 监听事件，固定为：'headTrackingEnabledChange'。 | 2627| callback | Callback<boolean\> | 是 | Callback对象，返回头动跟踪开关状态，true为打开，false为关闭。 | 2628 2629**错误码：** 2630 2631以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2632 2633| 错误码ID | 错误信息 | 2634| ------- | --------------------------------------------| 2635| 202 | Not system App. | 2636| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2637| 6800101 | Parameter verification failed. | 2638 2639**示例：** 2640 2641```ts 2642import { audio } from '@kit.AudioKit'; 2643 2644audioSpatializationManager.on('headTrackingEnabledChange', (isHeadTrackingEnabled: boolean) => { 2645 console.info(`isHeadTrackingEnabled: ${isHeadTrackingEnabled}`); 2646}); 2647``` 2648 2649### on('headTrackingEnabledChangeForAnyDevice')<sup>12+</sup> 2650 2651on(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void 2652 2653监听头动跟踪开关状态变化事件（当动跟踪开关状态发生变化时触发），使用callback方式返回结果。 2654 2655**系统接口：** 该接口为系统接口 2656 2657**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2658 2659**参数：** 2660 2661| 参数名 | 类型 | 必填 | 说明 | 2662| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 2663| type | string | 是 | 监听事件，固定为：'headTrackingEnabledChangeForAnyDevice'。 | 2664| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | 是 | Callback对象，返回设备信息和空间音频头动开关状态。 | 2665 2666**错误码：** 2667 2668以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2669 2670| 错误码ID | 错误信息 | 2671| ------- | --------------------------------------------| 2672| 202 | Not system App. | 2673| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2674| 6800101 | Parameter verification failed. | 2675 2676**示例：** 2677 2678```ts 2679import { audio } from '@kit.AudioKit'; 2680 2681audioSpatializationManager.on('headTrackingEnabledChangeForAnyDevice', (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 2682 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 2683 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 2684}); 2685``` 2686 2687### off('headTrackingEnabledChange')<sup>(deprecated)</sup> 2688 2689off(type: 'headTrackingEnabledChange', callback?: Callback<boolean\>): void 2690 2691取消监听头动跟踪开关状态变化事件，使用callback方式返回结果。 2692 2693> **说明：** 2694> 从 API version 11 开始支持，从 API version 12 开始废弃，建议使用[off(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void](#offheadtrackingenabledchangeforanydevice12)替代。 2695 2696**系统接口：** 该接口为系统接口 2697 2698**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2699 2700**参数：** 2701 2702| 参数名 | 类型 | 必填 | 说明 | 2703| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 2704| type | string | 是 | 监听事件，固定为：'headTrackingEnabledChange'。 | 2705| callback | Callback<boolean\> | 否 | 回调函数，返回头动跟踪开关状态，true为打开，false为关闭。 | 2706 2707**错误码：** 2708 2709以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2710 2711| 错误码ID | 错误信息 | 2712| ------- | --------------------------------------------| 2713| 202 | Not system App. | 2714| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2715| 6800101 | Parameter verification failed. | 2716 2717**示例：** 2718 2719```ts 2720import { audio } from '@kit.AudioKit'; 2721 2722// 取消该事件的所有监听 2723audioSpatializationManager.off('headTrackingEnabledChange'); 2724 2725// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听 2726let headTrackingEnabledChangeCallback = (isHeadTrackingEnabled: boolean) => { 2727 console.info(`isHeadTrackingEnabled: ${isHeadTrackingEnabled}`); 2728}; 2729 2730audioSpatializationManager.on('headTrackingEnabledChange', headTrackingEnabledChangeCallback); 2731 2732audioSpatializationManager.off('headTrackingEnabledChange', headTrackingEnabledChangeCallback); 2733``` 2734 2735### off('headTrackingEnabledChangeForAnyDevice')<sup>12+</sup> 2736 2737off(type: 'headTrackingEnabledChangeForAnyDevice', callback?: Callback<AudioSpatialEnabledStateForDevice\>): void 2738 2739取消监听头动跟踪开关状态变化事件，使用callback方式返回结果。 2740 2741**系统接口：** 该接口为系统接口 2742 2743**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2744 2745**参数：** 2746 2747| 参数名 | 类型 | 必填 | 说明 | 2748| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 2749| type | string | 是 | 监听事件，固定为：'headTrackingEnabledChangeForAnyDevice'。 | 2750| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | 是 | 回调函数，返回设备信息和空间音频头动开关状态。 | 2751 2752**错误码：** 2753 2754以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2755 2756| 错误码ID | 错误信息 | 2757| ------- | --------------------------------------------| 2758| 202 | Not system App. | 2759| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2760| 6800101 | Parameter verification failed. | 2761 2762**示例：** 2763 2764```ts 2765import { audio } from '@kit.AudioKit'; 2766 2767// 取消该事件的所有监听 2768audioSpatializationManager.off('headTrackingEnabledChangeForAnyDevice'); 2769 2770// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听 2771let headTrackingEnabledChangeForAnyDeviceCallback = (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 2772 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 2773 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 2774}; 2775 2776audioSpatializationManager.on('headTrackingEnabledChangeForAnyDevice', headTrackingEnabledChangeForAnyDeviceCallback); 2777 2778audioSpatializationManager.off('headTrackingEnabledChangeForAnyDevice', headTrackingEnabledChangeForAnyDeviceCallback); 2779``` 2780 2781### updateSpatialDeviceState<sup>11+</sup> 2782 2783updateSpatialDeviceState(spatialDeviceState: AudioSpatialDeviceState): void 2784 2785更新空间化设备状态，同步返回结果。 2786 2787**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2788 2789**系统接口：** 该接口为系统接口 2790 2791**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2792 2793**参数：** 2794 2795| 参数名 | 类型 | 必填 | 说明 | 2796| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 2797| spatialDeviceState | [AudioSpatialDeviceState](#audiospatialdevicestate11) | 是 | 需要更新的空间化设备状态。 | 2798 2799**错误码：** 2800 2801以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2802 2803| 错误码ID | 错误信息 | 2804| ------- | --------------------------------------------| 2805| 201 | Permission denied. | 2806| 202 | Not system App. | 2807| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2808| 6800101 | Parameter verification failed. | 2809 2810**示例：** 2811 2812```ts 2813import { audio } from '@kit.AudioKit'; 2814import { BusinessError } from '@kit.BasicServicesKit'; 2815 2816let spatialDeviceState: audio.AudioSpatialDeviceState = { 2817 address: "123", 2818 isSpatializationSupported: true, 2819 isHeadTrackingSupported: true, 2820 spatialDeviceType: audio.AudioSpatialDeviceType.SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE 2821}; 2822 2823try { 2824 audioSpatializationManager.updateSpatialDeviceState(spatialDeviceState); 2825 console.info(`AudioSpatializationManager updateSpatialDeviceState success`); 2826} catch (err) { 2827 let error = err as BusinessError; 2828 console.error(`ERROR: ${error}`); 2829} 2830``` 2831 2832### setSpatializationSceneType<sup>12+</sup> 2833 2834setSpatializationSceneType(spatializationSceneType: AudioSpatializationSceneType): void 2835 2836设置空间音频渲染场景类型，同步返回结果。 2837 2838**需要权限：** ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2839 2840**系统接口：** 该接口为系统接口 2841 2842**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2843 2844**参数：** 2845 2846| 参数名 | 类型 | 必填 | 说明 | 2847| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 2848| spatializationSceneType | [AudioSpatializationSceneType](#audiospatializationscenetype12) | 是 | 需要设置的空间音频渲染场景类型。 | 2849 2850**错误码：** 2851 2852以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2853 2854| 错误码ID | 错误信息 | 2855| ------- | --------------------------------------------| 2856| 201 | Permission denied. | 2857| 202 | Not system App. | 2858| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2859| 6800101 | Parameter verification failed. | 2860 2861**示例：** 2862 2863```ts 2864import { audio } from '@kit.AudioKit'; 2865import { BusinessError } from '@kit.BasicServicesKit'; 2866 2867try { 2868 audioSpatializationManager.setSpatializationSceneType(audio.AudioSpatializationSceneType.DEFAULT); 2869 console.info(`AudioSpatializationManager setSpatializationSceneType success`); 2870} catch (err) { 2871 let error = err as BusinessError; 2872 console.error(`ERROR: ${error}`); 2873} 2874``` 2875 2876### getSpatializationSceneType<sup>12+</sup> 2877 2878getSpatializationSceneType(): AudioSpatializationSceneType 2879 2880查询当前空间音频渲染场景类型，同步返回结果。 2881 2882**系统接口：** 该接口为系统接口 2883 2884**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2885 2886**返回值：** 2887 2888| 类型 | 说明 | 2889| ---------------------- | ------------------------------------------------------------ | 2890| [AudioSpatializationSceneType](#audiospatializationscenetype12) | 返回当前空间音频渲染场景类型。 | 2891 2892**错误码：** 2893 2894以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 2895 2896| 错误码ID | 错误信息 | 2897| ------- | --------------------------------------------| 2898| 202 | Not system App. | 2899 2900**示例：** 2901 2902```ts 2903import { audio } from '@kit.AudioKit'; 2904import { BusinessError } from '@kit.BasicServicesKit'; 2905 2906try { 2907 let spatializationSceneType: audio.AudioSpatializationSceneType = audioSpatializationManager.getSpatializationSceneType(); 2908 console.info(`AudioSpatializationManager spatializationSceneType: ${spatializationSceneType}`); 2909} catch (err) { 2910 let error = err as BusinessError; 2911 console.error(`ERROR: ${error}`); 2912} 2913``` 2914 2915## AudioSpatialDeviceState<sup>11+</sup> 2916 2917空间化设备状态。 2918 2919**系统接口：** 该接口为系统接口 2920 2921**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2922 2923| 名称 | 类型 | 可读 | 可写 | 说明 | 2924| ----------------------------- | -------------------------- | ---- | ---- | ---------- | 2925| address<sup>11+</sup> | string | 是 | 是 | 空间化设备地址。| 2926| isSpatializationSupported<sup>11+</sup> | boolean | 是 | 是 | 空间化设备是否支持空间音频渲染。| 2927| isHeadTrackingSupported<sup>11+</sup> | boolean | 是 | 是 | 空间化设备是否支持头动跟踪。| 2928| spatialDeviceType<sup>11+</sup> | [AudioSpatialDeviceType](#audiospatialdevicetype11) | 是 | 是 | 空间化设备类型。| 2929 2930**示例：** 2931 2932```ts 2933import { audio } from '@kit.AudioKit'; 2934 2935let spatialDeviceState: audio.AudioSpatialDeviceState = { 2936 address: "123", 2937 isSpatializationSupported: true, 2938 isHeadTrackingSupported: true, 2939 spatialDeviceType: audio.AudioSpatialDeviceType.SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE 2940}; 2941``` 2942 2943## AudioSpatialDeviceType<sup>11+</sup> 2944 2945枚举，空间化设备类型。 2946 2947**系统接口：** 该接口为系统接口 2948 2949**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2950 2951| 名称 | 值 | 说明 | 2952| ---------------------------------- | ------ | ------------------------- | 2953| SPATIAL_DEVICE_TYPE_NONE | 0 | 无空间化设备类型。 | 2954| SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE | 1 | 入耳式耳机。 | 2955| SPATIAL_DEVICE_TYPE_HALF_IN_EAR_HEADPHONE | 2 | 半入耳式耳机。 | 2956| SPATIAL_DEVICE_TYPE_OVER_EAR_HEADPHONE | 3 | 头戴式耳机。 | 2957| SPATIAL_DEVICE_TYPE_GLASSES | 4 | 眼镜式耳机。 | 2958| SPATIAL_DEVICE_TYPE_OTHERS | 5 | 其他空间化设备类型。| 2959 2960## AudioSpatializationSceneType<sup>12+</sup> 2961 2962枚举，空间音频渲染场景类型。 2963 2964**系统接口：** 该接口为系统接口 2965 2966**系统能力：** SystemCapability.Multimedia.Audio.Spatialization 2967 2968| 名称 | 值 | 说明 | 2969| ---------------------------------- | ------ | ------------------------- | 2970| DEFAULT | 0 | 空间音频默认渲染场景。 | 2971| MUSIC | 1 | 空间音频音乐渲染场景。 | 2972| MOVIE | 2 | 空间音频电影渲染场景。 | 2973| AUDIOBOOK | 3 | 空间音频有声读物渲染场景。 | 2974 2975## ToneType<sup>9+</sup> 2976 2977枚举，播放器的音调类型。 2978 2979**系统接口：** 该接口为系统接口 2980 2981**系统能力：** SystemCapability.Multimedia.Audio.Tone 2982 2983| 名称 | 值 | 说明 | 2984| :------------------------------------------------ | :----- | :----------------------------| 2985| TONE_TYPE_DIAL_0 | 0 | 键0的DTMF音。 | 2986| TONE_TYPE_DIAL_1 | 1 | 键1的DTMF音。 | 2987| TONE_TYPE_DIAL_2 | 2 | 键2的DTMF音。 | 2988| TONE_TYPE_DIAL_3 | 3 | 键3的DTMF音。 | 2989| TONE_TYPE_DIAL_4 | 4 | 键4的DTMF音。 | 2990| TONE_TYPE_DIAL_5 | 5 | 键5的DTMF音。 | 2991| TONE_TYPE_DIAL_6 | 6 | 键6的DTMF音。 | 2992| TONE_TYPE_DIAL_7 | 7 | 键7的DTMF音。 | 2993| TONE_TYPE_DIAL_8 | 8 | 键8的DTMF音。 | 2994| TONE_TYPE_DIAL_9 | 9 | 键9的DTMF音。 | 2995| TONE_TYPE_DIAL_S | 10 | 键*的DTMF音。 | 2996| TONE_TYPE_DIAL_P | 11 | 键#的DTMF音。 | 2997| TONE_TYPE_DIAL_A | 12 | 键A的DTMF音。 | 2998| TONE_TYPE_DIAL_B | 13 | 键B的DTMF音。 | 2999| TONE_TYPE_DIAL_C | 14 | 键C的DTMF音。 | 3000| TONE_TYPE_DIAL_D | 15 | 键D的DTMF音。 | 3001| TONE_TYPE_COMMON_SUPERVISORY_DIAL | 100 | 呼叫监管音调，拨号音。 | 3002| TONE_TYPE_COMMON_SUPERVISORY_BUSY | 101 | 呼叫监管音调，忙。 | 3003| TONE_TYPE_COMMON_SUPERVISORY_CONGESTION | 102 | 呼叫监管音调，拥塞。 | 3004| TONE_TYPE_COMMON_SUPERVISORY_RADIO_ACK | 103 | 呼叫监管音调，无线电 ACK。 | 3005| TONE_TYPE_COMMON_SUPERVISORY_RADIO_NOT_AVAILABLE | 104 | 呼叫监管音调，无线电不可用。 | 3006| TONE_TYPE_COMMON_SUPERVISORY_CALL_WAITING | 106 | 呼叫监管音调，呼叫等待。 | 3007| TONE_TYPE_COMMON_SUPERVISORY_RINGTONE | 107 | 呼叫监管音调，铃声。 | 3008| TONE_TYPE_COMMON_PROPRIETARY_BEEP | 200 | 专有声调，一般蜂鸣声。 | 3009| TONE_TYPE_COMMON_PROPRIETARY_ACK | 201 | 专有声调，ACK。 | 3010| TONE_TYPE_COMMON_PROPRIETARY_PROMPT | 203 | 专有声调，PROMPT。 | 3011| TONE_TYPE_COMMON_PROPRIETARY_DOUBLE_BEEP | 204 | 专有声调，双重蜂鸣声。 | 3012 3013## TonePlayer<sup>9+</sup> 3014 3015提供播放和管理DTMF（Dual Tone Multi Frequency，双音多频）音调的方法，包括各种系统监听音调、专有音调，如拨号音、通话回铃音等。 3016在调用TonePlayer的接口前，需要先通过[createTonePlayer](#audiocreatetoneplayer9)创建实例。 3017 3018**系统接口：** 该接口为系统接口 3019 3020### load<sup>9+</sup> 3021 3022load(type: ToneType, callback: AsyncCallback<void>): void 3023 3024加载DTMF音调配置。使用callback方式异步返回结果。 3025 3026**系统接口：** 该接口为系统接口 3027 3028**系统能力：** SystemCapability.Multimedia.Audio.Tone 3029 3030**参数：** 3031 3032| 参数名 | 类型 | 必填 | 说明 | 3033| :--------------| :-------------------------- | :-----| :------------------------------ | 3034| type | [ToneType](#tonetype9) | 是 | 配置的音调类型。 | 3035| callback | AsyncCallback<void\> | 是 | 回调函数。当加载DTMF音调配置成功，err为undefined，否则为错误对象。 | 3036 3037**示例：** 3038 3039```ts 3040import { BusinessError } from '@kit.BasicServicesKit'; 3041 3042tonePlayer.load(audio.ToneType.TONE_TYPE_DIAL_5, (err: BusinessError) => { 3043 if (err) { 3044 console.error(`callback call load failed error: ${err.message}`); 3045 return; 3046 } else { 3047 console.info('callback call load success'); 3048 } 3049}); 3050``` 3051 3052### load<sup>9+</sup> 3053 3054load(type: ToneType): Promise<void> 3055 3056加载DTMF音调配置。使用Promise方式异步返回结果。 3057 3058**系统接口：** 该接口为系统接口 3059 3060**系统能力：** SystemCapability.Multimedia.Audio.Tone 3061 3062**参数：** 3063 3064| 参数名 | 类型 | 必填 | 说明 | 3065| :------------- | :--------------------- | :--- | ---------------- | 3066| type | [ToneType](#tonetype9) | 是 | 配置的音调类型。 | 3067 3068**返回值：** 3069 3070| 类型 | 说明 | 3071| :--------------| :-------------------------- | 3072| Promise<void\> | Promise对象，无返回结果。 | 3073 3074**示例：** 3075 3076```ts 3077tonePlayer.load(audio.ToneType.TONE_TYPE_DIAL_1).then(() => { 3078 console.info('promise call load '); 3079}).catch(() => { 3080 console.error('promise call load fail'); 3081}); 3082``` 3083 3084### start<sup>9+</sup> 3085 3086start(callback: AsyncCallback<void>): void 3087 3088启动DTMF音调播放。使用callback方式异步返回结果。 3089 3090**系统接口：** 该接口为系统接口 3091 3092**系统能力：** SystemCapability.Multimedia.Audio.Tone 3093 3094**参数：** 3095 3096| 参数名 | 类型 | 必填 | 说明 | 3097| :------- | :------------------- | :--- | :----------------------------- | 3098| callback | AsyncCallback<void\> | 是 | 回调函数。当启动DTMF音调播放成功，err为undefined，否则为错误对象。 | 3099 3100**示例：** 3101 3102```ts 3103import { BusinessError } from '@kit.BasicServicesKit'; 3104 3105tonePlayer.start((err: BusinessError) => { 3106 if (err) { 3107 console.error(`callback call start failed error: ${err.message}`); 3108 return; 3109 } else { 3110 console.info('callback call start success'); 3111 } 3112}); 3113``` 3114 3115### start<sup>9+</sup> 3116 3117start(): Promise<void> 3118 3119启动DTMF音调播放。使用Promise方式异步返回结果。 3120 3121**系统接口：** 该接口为系统接口 3122 3123**系统能力：** SystemCapability.Multimedia.Audio.Tone 3124 3125**返回值：** 3126 3127| 类型 | 说明 | 3128| :------------- | :---------------------------- | 3129| Promise<void\> | Promise对象，无返回结果。 | 3130 3131**示例：** 3132 3133```ts 3134tonePlayer.start().then(() => { 3135 console.info('promise call start'); 3136}).catch(() => { 3137 console.error('promise call start fail'); 3138}); 3139``` 3140 3141### stop<sup>9+</sup> 3142 3143stop(callback: AsyncCallback<void>): void 3144 3145停止当前正在播放的音调。使用callback方式异步返回结果。 3146 3147**系统接口：** 该接口为系统接口 3148 3149**系统能力：** SystemCapability.Multimedia.Audio.Tone 3150 3151**参数：** 3152 3153| 参数名 | 类型 | 必填 | 说明 | 3154| :------- | :------------------- | :--- | :----------------------------- | 3155| callback | AsyncCallback<void\> | 是 | 回调函数。当停止当前正在播放的音调成功，err为undefined，否则为错误对象。 | 3156 3157**示例：** 3158 3159```ts 3160import { BusinessError } from '@kit.BasicServicesKit'; 3161 3162tonePlayer.stop((err: BusinessError) => { 3163 if (err) { 3164 console.error(`callback call stop error: ${err.message}`); 3165 return; 3166 } else { 3167 console.error('callback call stop success '); 3168 } 3169}); 3170``` 3171 3172### stop<sup>9+</sup> 3173 3174stop(): Promise<void> 3175 3176停止当前正在播放的音调。使用Promise方式异步返回结果。 3177 3178**系统接口：** 该接口为系统接口 3179 3180**系统能力：** SystemCapability.Multimedia.Audio.Tone 3181 3182**返回值：** 3183 3184| 类型 | 说明 | 3185| :------------- | :---------------------------- | 3186| Promise<void\> | Promise对象，无返回结果。 | 3187 3188**示例：** 3189 3190```ts 3191tonePlayer.stop().then(() => { 3192 console.info('promise call stop finish'); 3193}).catch(() => { 3194 console.error('promise call stop fail'); 3195}); 3196``` 3197 3198### release<sup>9+</sup> 3199 3200release(callback: AsyncCallback<void>): void 3201 3202释放与此TonePlayer对象关联的资源。使用callback方式异步返回结果。 3203 3204**系统接口：** 该接口为系统接口 3205 3206**系统能力：** SystemCapability.Multimedia.Audio.Tone 3207 3208**参数：** 3209 3210| 参数名 | 类型 | 必填 | 说明 | 3211| :------- | :------------------- | :--- | :---------------------------- | 3212| callback | AsyncCallback<void\> | 是 | 回调函数。当释放与此TonePlayer对象关联的资源成功，err为undefined，否则为错误对象。 | 3213 3214**示例：** 3215 3216```ts 3217import { BusinessError } from '@kit.BasicServicesKit'; 3218 3219tonePlayer.release((err: BusinessError) => { 3220 if (err) { 3221 console.error(`callback call release failed error: ${err.message}`); 3222 return; 3223 } else { 3224 console.info('callback call release success '); 3225 } 3226}); 3227``` 3228 3229### release<sup>9+</sup> 3230 3231release(): Promise<void> 3232 3233释放与此TonePlayer对象关联的资源。使用Promise方式异步返回结果。 3234 3235**系统接口：** 该接口为系统接口 3236 3237**系统能力：** SystemCapability.Multimedia.Audio.Tone 3238 3239**返回值：** 3240 3241| 类型 | 说明 | 3242| :------------- | :---------------------------- | 3243| Promise<void\> | Promise对象，无返回结果。 | 3244 3245**示例：** 3246 3247```ts 3248tonePlayer.release().then(() => { 3249 console.info('promise call release'); 3250}).catch(() => { 3251 console.error('promise call release fail'); 3252}); 3253``` 3254 3255## AsrProcessingController<sup>12+</sup> 3256 3257ASR处理控制器 3258 3259**系统接口：** 该接口为系统接口 3260 3261**系统能力：** SystemCapability.Multimedia.Audio.Capturer 3262 3263### setAsrAecMode<sup>12+</sup> 3264 3265setAsrAecMode(mode: AsrAecMode): boolean; 3266 3267设置ASR AEC模式，同步返回结果。 3268 3269**系统接口：** 该接口为系统接口 3270 3271**系统能力：** SystemCapability.Multimedia.Audio.Capturer 3272 3273**参数：** 3274 3275| 参数名| 类型 | 必填 | 说明 | 3276|-------|----------------------------|-------|-------| 3277| mode | [AsrAecMode](#asraecmode12) | 是 |ASR AEC 模式 | 3278 3279**返回值：** 3280 3281| 类型 | 说明 | 3282|-------|---------------------------------------| 3283| boolean | 返回设置ASR AEC模式结果，true为设置成功，false为设置失败。 | 3284 3285**错误码：** 3286 3287以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 3288 3289| 错误码ID | 错误信息 | 3290|---------|------------------------------------------| 3291| 202 | Caller is not a system application. | 3292| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3293| 6800101 | Parameter verification failed. | 3294| 6800104 | Operation not allowed. | 3295 3296**示例：** 3297 3298```ts 3299let flag = asrProcessingController.setAsrAecMode(audio.AsrAecMode.BYPASS); 3300``` 3301 3302### getAsrAecMode<sup>12+</sup> 3303 3304getAsrAecMode(): AsrAecMode; 3305 3306获取ASR AEC模式，同步返回结果。 3307 3308**系统接口：** 该接口为系统接口 3309 3310**系统能力：** SystemCapability.Multimedia.Audio.Capturer 3311 3312**返回值：** 3313 3314| 类型 | 说明 | 3315|-------|-------| 3316| [AsrAecMode](#asraecmode12) |ASR AEC 模式 | 3317 3318**错误码：** 3319 3320以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 3321 3322| 错误码ID | 错误信息 | 3323|---------|------------------------------------------| 3324| 202 | Caller is not a system application. | 3325| 6800104 | Operation not allowed. | 3326 3327 3328**示例：** 3329 3330```ts 3331let mode = asrProcessingController.getAsrAecMode(); 3332``` 3333 3334### setAsrNoiseSuppressionMode<sup>12+</sup> 3335 3336setAsrNoiseSuppressionMode(mode: AsrNoiseSuppressionMode): boolean; 3337 3338设置ASR 噪音抑制模式，同步返回结果。 3339 3340**系统接口：** 该接口为系统接口 3341 3342**系统能力：** SystemCapability.Multimedia.Audio.Capturer 3343 3344**参数：** 3345 3346| 参数名| 类型 | 必填 | 说明 | 3347|-------|-------------------------------------------------------|-------|-------| 3348| mode | [AsrNoiseSuppressionMode](#asrnoisesuppressionmode12) | 是 |ASR 噪音抑制模式 | 3349 3350**返回值：** 3351 3352| 类型 | 说明 | 3353|-------|----------------------------------------| 3354| boolean | 返回设置ASR 噪音抑制模式结果，true为设置成功，false为设置失败。 | 3355 3356**错误码：** 3357 3358以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 3359 3360| 错误码ID | 错误信息 | 3361|---------|------------------------------------------| 3362| 202 | Caller is not a system application. | 3363| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3364| 6800101 | Parameter verification failed. | 3365| 6800104 | Operation not allowed. | 3366 3367**示例：** 3368 3369```ts 3370let flag = asrProcessingController.setAsrNoiseSuppressionMode(audio.AsrNoiseSuppressionMode.BYPASS); 3371``` 3372 3373### getAsrNoiseSuppressionMode<sup>12+</sup> 3374 3375getAsrNoiseSuppressionMode(): AsrNoiseSuppressionMode; 3376 3377获取ASR 噪音抑制模式，同步返回结果。 3378 3379**系统接口：** 该接口为系统接口 3380 3381**系统能力：** SystemCapability.Multimedia.Audio.Capturer 3382 3383**返回值：** 3384 3385| 类型 |说明 | 3386|-------------------------|-------| 3387| [AsrNoiseSuppressionMode](#asrnoisesuppressionmode12) |ASR 噪音抑制模式 | 3388 3389**错误码：** 3390 3391以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 3392 3393| 错误码ID | 错误信息 | 3394|---------|------------------------------------------| 3395| 202 | Caller is not a system application. | 3396| 6800104 | Operation not allowed. | 3397 3398**示例：** 3399 3400```ts 3401let mode = asrProcessingController.getAsrNoiseSuppressionMode(); 3402``` 3403 3404### isWhispering<sup>12+</sup> 3405 3406isWhispering(): boolean; 3407 3408查询耳语状态。 3409 3410**系统接口：** 该接口为系统接口 3411 3412**系统能力：** SystemCapability.Multimedia.Audio.Capturer 3413 3414**返回值：** 3415 3416| 类型 | 说明 | 3417|-------|--------------------------| 3418| boolean | 返回耳语状态，true为开启，false为关闭。 | 3419 3420**错误码：** 3421 3422以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 3423 3424| 错误码ID | 错误信息 | 3425|---------|------------------------------------------| 3426| 202 | Caller is not a system application. | 3427| 6800104 | Operation not allowed. | 3428 3429**示例：** 3430 3431```ts 3432let flag = asrProcessingController.isWhispering(); 3433``` 3434 3435### setAsrWhisperDetectionMode<sup>12+</sup> 3436 3437setAsrWhisperDetectionMode(mode: AsrWhisperDetectionMode): boolean 3438 3439设置耳语检测模式。 3440 3441**系统接口：** 该接口为系统接口 3442 3443**系统能力：** SystemCapability.Multimedia.Audio.Capturer 3444 3445**参数：** 3446 3447| 参数名 | 类型 | 必填 | 说明 | 3448|------|---------------------|-------|--------| 3449| mode | [AsrWhisperDetectionMode](#asrwhisperdetectionmode12) | 是 | 耳语检测模式 | 3450 3451**返回值：** 3452 3453| 类型 | 说明 | 3454|-------|----------------------------------------| 3455| boolean | 返回设置耳语检测模式结果，true为设置成功，false为设置失败。 | 3456 3457**错误码：** 3458 3459以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 3460 3461| 错误码ID | 错误信息 | 3462|---------|------------------------------------------| 3463| 202 | Caller is not a system application. | 3464| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified; 2.Incorrect parameter types. | 3465| 6800101 | Parameter verification failed. | 3466| 6800104 | Operation not allowed. | 3467 3468**示例：** 3469 3470```ts 3471let flag = asrProcessingController.setAsrWhisperDetectionMode(audio.AsrWhisperDetectionMode.BYPASS); 3472``` 3473 3474 3475### getAsrWhisperDetectionMode<sup>12+</sup> 3476 3477getAsrWhisperDetectionMode(): AsrWhisperDetectionMode 3478 3479获取耳语检测模式，同步返回结果。 3480 3481**系统接口：** 该接口为系统接口 3482 3483**系统能力：** SystemCapability.Multimedia.Audio.Capturer 3484 3485**返回值：** 3486 3487| 类型 | 说明 | 3488|-------|--------| 3489| [AsrWhisperDetectionMode](#asrwhisperdetectionmode12) | 耳语检测模式 | 3490 3491**错误码：** 3492 3493以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 3494 3495| 错误码ID | 错误信息 | 3496|---------|------------------------------------------| 3497| 202 | Caller is not a system application. | 3498| 6800104 | Operation not allowed. | 3499 3500**示例：** 3501 3502```ts 3503let mode = asrProcessingController.getAsrWhisperDetectionMode(); 3504``` 3505 3506 3507### setAsrVoiceControlMode<sup>12+</sup> 3508 3509setAsrVoiceControlMode(mode: AsrVoiceControlMode, enable: boolean): boolean 3510 3511设置在系统通话中上报modem及通话录音的上行通路的ASR音频通路选择。 3512 3513**系统接口：** 该接口为系统接口 3514 3515**系统能力：** SystemCapability.Multimedia.Audio.Capturer 3516 3517**参数：** 3518 3519| 参数名 | 类型 | 必填 | 说明 | 3520|------|---------------------|-------|--------| 3521| mode | [AsrVoiceControlMode](#asrvoicecontrolmode12) | 是 | 音频通路模式 | 3522| enable | boolean | 是 | 开关状态 | 3523 3524**返回值：** 3525 3526| 类型 | 说明 | 3527|-------|----------------------------------------------------------------| 3528| boolean | 返回设置在系统通话中上报modem及通话录音的上行通路的ASR音频通路选择的结果，true为设置成功，false为设置失败。 | 3529 3530**错误码：** 3531 3532以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 3533 3534| 错误码ID | 错误信息 | 3535|---------|------------------------------------------| 3536| 202 | Caller is not a system application. | 3537| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified; 2.Incorrect parameter types. | 3538| 6800101 | Parameter verification failed. | 3539| 6800104 | Operation not allowed. | 3540 3541**示例：** 3542 3543```ts 3544let flag = asrProcessingController.setAsrVoiceControlMode(audio.AsrVoiceControlMode.AUDIO_2_VOICE_TX, true); 3545``` 3546 3547### setAsrVoiceMuteMode<sup>12+</sup> 3548 3549setAsrVoiceMuteMode(mode: AsrVoiceMuteMode, enable: boolean): boolean 3550 3551在系统通话中，对ASR音频通路进行静音控制。 3552 3553**系统接口：** 该接口为系统接口 3554 3555**系统能力：** SystemCapability.Multimedia.Audio.Capturer 3556 3557**参数：** 3558 3559| 参数名 | 类型 | 必填 | 说明 | 3560|------|---------------------------------------|-------|----------| 3561| mode | [AsrVoiceMuteMode](#asrvoicemutemode12) | 是 | 静音控制模式 | 3562| enable | boolean | 是 | 开关状态 | 3563 3564**返回值：** 3565 3566| 类型 | 说明 | 3567|-------|--------------------------------------------------| 3568| boolean | 返回在系统通话中，对ASR音频通路进行静音控制的结果，true为设置成功，false为设置失败。 | 3569 3570**错误码：** 3571 3572以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 3573 3574| 错误码ID | 错误信息 | 3575|---------|------------------------------------------| 3576| 202 | Caller is not a system application. | 3577| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified; 2.Incorrect parameter types. | 3578| 6800101 | Parameter verification failed. | 3579| 6800104 | Operation not allowed. | 3580 3581**示例：** 3582 3583```ts 3584let flag = asrProcessingController.setAsrVoiceMuteMode(audio.AsrVoiceMuteMode.OUTPUT_MUTE, true); 3585```