1# Interface (AudioRoutingManager) 2 3> **NOTE** 4> 5> - The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 6> - The initial APIs of this interface are supported since API version 9. 7 8This interface implements audio routing management. 9 10Before calling any API in AudioRoutingManager, you must use [getRoutingManager](arkts-apis-audio-AudioManager.md#getroutingmanager9) to obtain an AudioRoutingManager instance. 11 12## Modules to Import 13 14```ts 15import { audio } from '@kit.AudioKit'; 16``` 17 18## getDevices<sup>9+</sup> 19 20getDevices(deviceFlag: DeviceFlag, callback: AsyncCallback<AudioDeviceDescriptors>): void 21 22Obtains the audio devices with a specific flag. This API uses an asynchronous callback to return the result. 23 24**System capability**: SystemCapability.Multimedia.Audio.Device 25 26**Parameters** 27 28| Name | Type | Mandatory| Description | 29| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 30| deviceFlag | [DeviceFlag](arkts-apis-audio-e.md#deviceflag) | Yes | Audio device flag. | 31| callback | AsyncCallback<[AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the audio devices obtained; otherwise, **err** is an error object.| 32 33**Example** 34 35```ts 36import { BusinessError } from '@kit.BasicServicesKit'; 37 38audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (err: BusinessError, value: audio.AudioDeviceDescriptors) => { 39 if (err) { 40 console.error(`Failed to obtain the device list. ${err}`); 41 return; 42 } 43 console.info('Callback invoked to indicate that the device list is obtained.'); 44}); 45``` 46 47## getDevices<sup>9+</sup> 48 49getDevices(deviceFlag: DeviceFlag): Promise<AudioDeviceDescriptors> 50 51Obtains the audio devices with a specific flag. This API uses a promise to return the result. 52 53**System capability**: SystemCapability.Multimedia.Audio.Device 54 55**Parameters** 56 57| Name | Type | Mandatory| Description | 58| ---------- | ------------------------- | ---- | ---------------- | 59| deviceFlag | [DeviceFlag](arkts-apis-audio-e.md#deviceflag) | Yes | Audio device flag.| 60 61**Return value** 62 63| Type | Description | 64| ------------------------------------------------------------ | ------------------------- | 65| Promise<[AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors)> | Promise used to return the device list.| 66 67**Example** 68 69```ts 70audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data: audio.AudioDeviceDescriptors) => { 71 console.info('Promise returned to indicate that the device list is obtained.'); 72}); 73``` 74 75## getDevicesSync<sup>10+</sup> 76 77getDevicesSync(deviceFlag: DeviceFlag): AudioDeviceDescriptors 78 79Obtains the audio devices with a specific flag. This API returns the result synchronously. 80 81**System capability**: SystemCapability.Multimedia.Audio.Device 82 83**Parameters** 84 85| Name | Type | Mandatory| Description | 86| ---------- | ------------------------- | ---- | ---------------- | 87| deviceFlag | [DeviceFlag](arkts-apis-audio-e.md#deviceflag) | Yes | Audio device flag.| 88 89**Return value** 90 91| Type | Description | 92| ------------------------------------------------------------ | ------------------------- | 93| [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | Device list.| 94 95**Error codes** 96 97For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 98 99| ID| Error Message| 100| ------- | --------------------------------------------| 101| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 102| 6800101 | Parameter verification failed. | 103 104**Example** 105 106```ts 107import { BusinessError } from '@kit.BasicServicesKit'; 108 109try { 110 let data: audio.AudioDeviceDescriptors = audioRoutingManager.getDevicesSync(audio.DeviceFlag.OUTPUT_DEVICES_FLAG); 111 console.info(`Indicate that the device list is obtained ${data}`); 112} catch (err) { 113 let error = err as BusinessError; 114 console.error(`Failed to obtain the device list. ${error}`); 115} 116``` 117 118## isMicBlockDetectionSupported<sup>13+</sup> 119 120isMicBlockDetectionSupported(): Promise<boolean> 121 122Checks whether the current device supports microphone blocking detection. This API uses a promise to return the result. 123 124**System capability**: SystemCapability.Multimedia.Audio.Device 125 126**Return value** 127 128| Type | Description | 129| ---------------------- | ------------------------------------------------------------ | 130| Promise<boolean> | Promise used to return the result. The value **true** means that the current device supports microphone blocking detection, and **false** means the opposite.| 131 132**Example** 133 134```ts 135audioRoutingManager.isMicBlockDetectionSupported().then((value: boolean) => { 136 console.info(`Query whether microphone block detection is supported on current device result is ${value}.`); 137}); 138``` 139 140## on('micBlockStatusChanged')<sup>13+</sup> 141 142on(type: 'micBlockStatusChanged', callback: Callback<DeviceBlockStatusInfo\>): void 143 144Subscribes to the microphone blocked status change event. This API uses an asynchronous callback to return the result. 145 146Before using this API, check whether the current device supports microphone blocking detection. This event is triggered when the microphone blocked status changes during recording. Currently, this API takes effect only for the microphone on the local device. 147 148**System capability**: SystemCapability.Multimedia.Audio.Device 149 150**Parameters** 151 152| Name | Type | Mandatory| Description | 153| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 154| type | string | Yes | Event type. The event **'micBlockStatusChanged'** is triggered when the microphone blocked status is changed.| 155| callback | Callback<[DeviceBlockStatusInfo](arkts-apis-audio-i.md#deviceblockstatusinfo13)\> | Yes | Callback used to return the microphone blocked status and device information.| 156 157**Error codes** 158 159For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 160 161| ID| Error Message| 162| ------- | --------------------------------------------| 163| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 164| 6800101 | Parameter verification failed. | 165 166**Example** 167 168```ts 169// Before the subscription, check whether the current device supports detection. 170audioRoutingManager.isMicBlockDetectionSupported().then((value: boolean) => { 171 console.info(`Query whether microphone block detection is supported on current device result is ${value}.`); 172 if (value) { 173 audioRoutingManager.on('micBlockStatusChanged', (micBlockStatusChanged: audio.DeviceBlockStatusInfo) => { 174 console.info(`block status : ${micBlockStatusChanged.blockStatus} `); 175 }); 176 } 177}); 178``` 179 180## off('micBlockStatusChanged')<sup>13+</sup> 181 182off(type: 'micBlockStatusChanged', callback?: Callback<DeviceBlockStatusInfo\>): void 183 184Unsubscribes from the microphone blocked status change event. This API uses an asynchronous callback to return the result. 185 186**System capability**: SystemCapability.Multimedia.Audio.Device 187 188**Parameters** 189 190| Name | Type | Mandatory| Description | 191| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 192| type | string | Yes | Event type. The event **'micBlockStatusChanged'** is triggered when the microphone blocked status is changed.| 193| callback | Callback<[DeviceBlockStatusInfo](arkts-apis-audio-i.md#deviceblockstatusinfo13)\> | No | Callback used to return the microphone blocked status and device information.| 194 195**Error codes** 196 197For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 198 199| ID| Error Message| 200| ------- | --------------------------------------------| 201| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 202| 6800101 | Parameter verification failed. | 203 204**Example** 205 206```ts 207// Cancel all subscriptions to the event. 208audioRoutingManager.off('micBlockStatusChanged'); 209 210// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 211let micBlockStatusCallback = (micBlockStatusChanged: audio.DeviceBlockStatusInfo) => { 212 console.info(`block status : ${micBlockStatusChanged.blockStatus} `); 213}; 214 215audioRoutingManager.on('micBlockStatusChanged', micBlockStatusCallback); 216 217audioRoutingManager.off('micBlockStatusChanged', micBlockStatusCallback); 218``` 219 220## on('deviceChange')<sup>9+</sup> 221 222on(type: 'deviceChange', deviceFlag: DeviceFlag, callback: Callback<DeviceChangeAction\>): void 223 224Subscribes to the event indicating that the connection status of an audio device is changed. This API uses an asynchronous callback to return the result. 225 226**System capability**: SystemCapability.Multimedia.Audio.Device 227 228**Parameters** 229 230| Name | Type | Mandatory| Description | 231| :------- | :--------------------------------------------------- | :--- |:------------------------| 232| type | string | Yes | Event type. The event **'deviceChange'** is triggered when the connection status of an audio device is changed.| 233| deviceFlag | [DeviceFlag](arkts-apis-audio-e.md#deviceflag) | Yes | Audio device flag. | 234| callback | Callback<[DeviceChangeAction](arkts-apis-audio-i.md#devicechangeaction)\> | Yes | Callback used to return the device change details. | 235 236**Error codes** 237 238For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 239 240| ID| Error Message| 241| ------- | --------------------------------------------| 242| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 243| 6800101 | Parameter verification failed. | 244 245**Example** 246 247```ts 248audioRoutingManager.on('deviceChange', audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (deviceChanged: audio.DeviceChangeAction) => { 249 console.info('device change type : ' + deviceChanged.type); 250 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 251 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 252 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 253}); 254``` 255 256## off('deviceChange')<sup>9+</sup> 257 258off(type: 'deviceChange', callback?: Callback<DeviceChangeAction\>): void 259 260Unsubscribes from the event indicating that the connection status of an audio device is changed. This API uses an asynchronous callback to return the result. 261 262**System capability**: SystemCapability.Multimedia.Audio.Device 263 264**Parameters** 265 266| Name | Type | Mandatory| Description | 267| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 268| type | string | Yes | Event type. The event **'deviceChange'** is triggered when the connection status of an audio device is changed.| 269| callback | Callback<[DeviceChangeAction](arkts-apis-audio-i.md#devicechangeaction)> | No | Callback used to return the device change details.| 270 271**Error codes** 272 273For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 274 275| ID| Error Message| 276| ------- | --------------------------------------------| 277| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 278| 6800101 | Parameter verification failed. | 279 280**Example** 281 282```ts 283// Cancel all subscriptions to the event. 284audioRoutingManager.off('deviceChange'); 285 286// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 287let deviceChangeCallback = (deviceChanged: audio.DeviceChangeAction) => { 288 console.info('device change type : ' + deviceChanged.type); 289 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 290 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 291 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 292}; 293 294audioRoutingManager.on('deviceChange', audio.DeviceFlag.OUTPUT_DEVICES_FLAG, deviceChangeCallback); 295 296audioRoutingManager.off('deviceChange', deviceChangeCallback); 297``` 298 299## setCommunicationDevice<sup>9+</sup> 300 301setCommunicationDevice(deviceType: CommunicationDeviceType, active: boolean, callback: AsyncCallback<void>): void 302 303Sets a communication device to the active state. This API uses an asynchronous callback to return the result. 304 305This API will be deprecated in a later version due to function design is changed. You are not advised to use it. 306 307You are advised to use the [AVCastPicker component](../../media/avsession/using-switch-call-devices.md) provided by AVSession to switch between call devices. 308 309**System capability**: SystemCapability.Multimedia.Audio.Communication 310 311**Parameters** 312 313| Name | Type | Mandatory| Description | 314| ---------- | ------------------------------------- | ---- |-------------------------| 315| deviceType | [CommunicationDeviceType](arkts-apis-audio-e.md#communicationdevicetype9) | Yes | Audio device flag. | 316| active | boolean | Yes | Active state to set. The value **true** means to set the device to the active state, and **false** means the opposite.| 317| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 318 319**Example** 320 321```ts 322import { BusinessError } from '@kit.BasicServicesKit'; 323 324audioRoutingManager.setCommunicationDevice(audio.CommunicationDeviceType.SPEAKER, true, (err: BusinessError) => { 325 if (err) { 326 console.error(`Failed to set the active status of the device. ${err}`); 327 return; 328 } 329 console.info('Callback invoked to indicate that the device is set to the active status.'); 330}); 331``` 332 333## getAvailableDevices<sup>12+</sup> 334 335getAvailableDevices(deviceUsage: DeviceUsage): AudioDeviceDescriptors 336 337Obtains the available audio devices. This API returns the result synchronously. 338 339**System capability**: SystemCapability.Multimedia.Audio.Device 340 341**Parameters** 342 343| Name | Type | Mandatory| Description | 344| ---------- | ------------------------- | ---- | ---------------- | 345| deviceUsage| [DeviceUsage](arkts-apis-audio-e.md#deviceusage12) | Yes | Audio device type (classified by usage).| 346 347**Return value** 348 349| Type | Description | 350| ------------------------------------------------------------ | ------------------------- | 351| [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | Device list.| 352 353**Error codes** 354 355For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 356 357| ID| Error Message| 358| ------- | --------------------------------------------| 359| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 360| 6800101 | Parameter verification failed. | 361 362**Example** 363 364```ts 365import { BusinessError } from '@kit.BasicServicesKit'; 366 367try { 368 let data: audio.AudioDeviceDescriptors = audioRoutingManager.getAvailableDevices(audio.DeviceUsage.MEDIA_OUTPUT_DEVICES); 369 console.info(`Indicate that the device list is obtained ${data}`); 370} catch (err) { 371 let error = err as BusinessError; 372 console.error(`Failed to obtain the device list. ${error}`); 373} 374``` 375 376## on('availableDeviceChange')<sup>12+</sup> 377 378on(type: 'availableDeviceChange', deviceUsage: DeviceUsage, callback: Callback<DeviceChangeAction\>): void 379 380Subscribes to the event indicating that the connection status of an available audio device is changed. This API uses an asynchronous callback to return the result. 381 382**System capability**: SystemCapability.Multimedia.Audio.Device 383 384**Parameters** 385 386| Name | Type | Mandatory| Description | 387| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 388| type | string | Yes | Event type. The event **'availableDeviceChange'** is triggered when the connection status of available audio devices is changed.| 389| deviceUsage | [DeviceUsage](arkts-apis-audio-e.md#deviceusage12) | Yes | Audio device type (classified by usage). | 390| callback | Callback<[DeviceChangeAction](arkts-apis-audio-i.md#devicechangeaction)\> | Yes | Callback used to return the device change details.| 391 392**Error codes** 393 394For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 395 396| ID| Error Message| 397| ------- | --------------------------------------------| 398| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 399| 6800101 | Parameter verification failed. | 400 401**Example** 402 403```ts 404audioRoutingManager.on('availableDeviceChange', audio.DeviceUsage.MEDIA_OUTPUT_DEVICES, (deviceChanged: audio.DeviceChangeAction) => { 405 console.info('device change type : ' + deviceChanged.type); 406 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 407 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 408 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 409}); 410``` 411 412## off('availableDeviceChange')<sup>12+</sup> 413 414off(type: 'availableDeviceChange', callback?: Callback<DeviceChangeAction\>): void 415 416Unsubscribes from the event indicating that the connection status of an available audio device is changed. This API uses an asynchronous callback to return the result. 417 418**System capability**: SystemCapability.Multimedia.Audio.Device 419 420**Parameters** 421 422| Name | Type | Mandatory| Description | 423| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 424| type | string | Yes | Event type. The event **'availableDeviceChange'** is triggered when the connection status of available audio devices is changed.| 425| callback | Callback<[DeviceChangeAction](arkts-apis-audio-i.md#devicechangeaction)> | No | Callback used to return the available device change details.| 426 427**Error codes** 428 429For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 430 431| ID| Error Message| 432| ------- | --------------------------------------------| 433| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 434| 6800101 | Parameter verification failed. | 435 436**Example** 437 438```ts 439// Cancel all subscriptions to the event. 440audioRoutingManager.off('availableDeviceChange'); 441 442// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 443let availableDeviceChangeCallback = (deviceChanged: audio.DeviceChangeAction) => { 444 console.info('device change type : ' + deviceChanged.type); 445 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 446 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 447 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 448}; 449 450audioRoutingManager.on('availableDeviceChange', audio.DeviceUsage.MEDIA_OUTPUT_DEVICES, availableDeviceChangeCallback); 451 452audioRoutingManager.off('availableDeviceChange', availableDeviceChangeCallback); 453``` 454 455## setCommunicationDevice<sup>9+</sup> 456 457setCommunicationDevice(deviceType: CommunicationDeviceType, active: boolean): Promise<void> 458 459Sets a communication device to the active state. This API uses a promise to return the result. 460 461This API will be deprecated in a later version due to function design is changed. You are not advised to use it. 462 463You are advised to use the [AVCastPicker component](../../media/avsession/using-switch-call-devices.md) provided by AVSession to switch between call devices. 464 465**System capability**: SystemCapability.Multimedia.Audio.Communication 466 467**Parameters** 468 469| Name | Type | Mandatory| Description | 470| ---------- | ----------------------------------------------------- | ---- | ------------------ | 471| deviceType | [CommunicationDeviceType](arkts-apis-audio-e.md#communicationdevicetype9) | Yes | Active audio device type.| 472| active | boolean | Yes | Active state to set. The value **true** means to set the device to the active state, and **false** means the opposite. | 473 474**Return value** 475 476| Type | Description | 477| ------------------- | ------------------------------- | 478| Promise<void> | Promise that returns no value.| 479 480**Example** 481 482```ts 483audioRoutingManager.setCommunicationDevice(audio.CommunicationDeviceType.SPEAKER, true).then(() => { 484 console.info('Promise returned to indicate that the device is set to the active status.'); 485}); 486``` 487 488## isCommunicationDeviceActive<sup>9+</sup> 489 490isCommunicationDeviceActive(deviceType: CommunicationDeviceType, callback: AsyncCallback<boolean>): void 491 492Checks whether a communication device is active. This API uses an asynchronous callback to return the result. 493 494**System capability**: SystemCapability.Multimedia.Audio.Communication 495 496**Parameters** 497 498| Name | Type | Mandatory| Description | 499| ---------- | ---------------------------------------------------- | ---- | ------------------------ | 500| deviceType | [CommunicationDeviceType](arkts-apis-audio-e.md#communicationdevicetype9) | Yes | Active audio device type. | 501| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true** if the device is active or **false** if not active; otherwise, **err** is an error object.| 502 503**Example** 504 505```ts 506import { BusinessError } from '@kit.BasicServicesKit'; 507 508audioRoutingManager.isCommunicationDeviceActive(audio.CommunicationDeviceType.SPEAKER, (err: BusinessError, value: boolean) => { 509 if (err) { 510 console.error(`Failed to obtain the active status of the device. ${err}`); 511 return; 512 } 513 console.info('Callback invoked to indicate that the active status of the device is obtained.'); 514}); 515``` 516 517## isCommunicationDeviceActive<sup>9+</sup> 518 519isCommunicationDeviceActive(deviceType: CommunicationDeviceType): Promise<boolean> 520 521Checks whether a communication device is active. This API uses a promise to return the result. 522 523**System capability**: SystemCapability.Multimedia.Audio.Communication 524 525**Parameters** 526 527| Name | Type | Mandatory| Description | 528| ---------- | ---------------------------------------------------- | ---- | ------------------ | 529| deviceType | [CommunicationDeviceType](arkts-apis-audio-e.md#communicationdevicetype9) | Yes | Active audio device type.| 530 531**Return value** 532 533| Type | Description | 534| ---------------------- | ------------------------------- | 535| Promise<boolean> | Promise used to return the result. The value **true** means that the device is active, and **false** means the opposite.| 536 537**Example** 538 539```ts 540audioRoutingManager.isCommunicationDeviceActive(audio.CommunicationDeviceType.SPEAKER).then((value: boolean) => { 541 console.info(`Promise returned to indicate that the active status of the device is obtained ${value}.`); 542}); 543``` 544 545## isCommunicationDeviceActiveSync<sup>10+</sup> 546 547isCommunicationDeviceActiveSync(deviceType: CommunicationDeviceType): boolean 548 549Checks whether a communication device is active. This API returns the result synchronously. 550 551**System capability**: SystemCapability.Multimedia.Audio.Communication 552 553**Parameters** 554 555| Name | Type | Mandatory| Description | 556| ---------- | ---------------------------------------------------- | ---- | ------------------ | 557| deviceType | [CommunicationDeviceType](arkts-apis-audio-e.md#communicationdevicetype9) | Yes | Active audio device type.| 558 559**Return value** 560 561| Type | Description | 562| ---------------------- | ------------------------------- | 563| boolean | Check result. The value **true** means that the device is active, and **false** means the opposite.| 564 565**Error codes** 566 567For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 568 569| ID| Error Message| 570| ------- | --------------------------------------------| 571| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 572| 6800101 | Parameter verification failed. | 573 574**Example** 575 576```ts 577import { BusinessError } from '@kit.BasicServicesKit'; 578 579try { 580 let value: boolean = audioRoutingManager.isCommunicationDeviceActiveSync(audio.CommunicationDeviceType.SPEAKER); 581 console.info(`Indicate that the active status of the device is obtained ${value}.`); 582} catch (err) { 583 let error = err as BusinessError; 584 console.error(`Failed to obtain the active status of the device ${error}.`); 585} 586``` 587 588## getPreferOutputDeviceForRendererInfo<sup>10+</sup> 589 590getPreferOutputDeviceForRendererInfo(rendererInfo: AudioRendererInfo, callback: AsyncCallback<AudioDeviceDescriptors>): void 591 592Obtains the output device with the highest priority based on the audio renderer information. This API uses an asynchronous callback to return the result. 593 594**System capability**: SystemCapability.Multimedia.Audio.Device 595 596**Parameters** 597 598| Name | Type | Mandatory| Description | 599| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 600| rendererInfo | [AudioRendererInfo](arkts-apis-audio-i.md#audiorendererinfo8) | Yes | Audio renderer information. | 601| callback | AsyncCallback<[AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the output device with the highest priority obtained; otherwise, **err** is an error object.| 602 603**Error codes** 604 605For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 606 607| ID| Error Message | 608| ------- |--------------------------------------------------| 609| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 610| 6800101 | Parameter verification failed. Return by callback. | 611| 6800301 | System error. Return by callback. | 612 613**Example** 614```ts 615import { audio } from '@kit.AudioKit'; 616import { BusinessError } from '@kit.BasicServicesKit'; 617 618let rendererInfo: audio.AudioRendererInfo = { 619 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music. Set this parameter based on the service scenario. 620 rendererFlags: 0 // AudioRenderer flag. 621}; 622 623async function getPreferOutputDevice() { 624 audioRoutingManager.getPreferOutputDeviceForRendererInfo(rendererInfo, (err: BusinessError, desc: audio.AudioDeviceDescriptors) => { 625 if (err) { 626 console.error(`Result ERROR: ${err}`); 627 } else { 628 console.info(`device descriptor: ${desc}`); 629 } 630 }); 631} 632``` 633 634## getPreferOutputDeviceForRendererInfo<sup>10+</sup> 635getPreferOutputDeviceForRendererInfo(rendererInfo: AudioRendererInfo): Promise<AudioDeviceDescriptors> 636 637Obtains the output device with the highest priority based on the audio renderer information. This API uses a promise to return the result. 638 639**System capability**: SystemCapability.Multimedia.Audio.Device 640 641**Parameters** 642 643| Name | Type | Mandatory| Description | 644| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 645| rendererInfo | [AudioRendererInfo](arkts-apis-audio-i.md#audiorendererinfo8) | Yes | Audio renderer information. | 646 647**Return value** 648 649| Type | Description | 650| --------------------- | --------------------------- | 651| Promise<[AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors)> | Promise used to return the information about the output device with the highest priority.| 652 653**Error codes** 654 655For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 656 657| ID| Error Message | 658| ------- |-------------------------------------------------| 659| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 660| 6800101 | Parameter verification failed. Return by promise. | 661| 6800301 | System error. Return by promise. | 662 663**Example** 664 665```ts 666import { audio } from '@kit.AudioKit'; 667import { BusinessError } from '@kit.BasicServicesKit'; 668 669let rendererInfo: audio.AudioRendererInfo = { 670 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music. Set this parameter based on the service scenario. 671 rendererFlags: 0 // AudioRenderer flag. 672}; 673 674async function getPreferOutputDevice() { 675 audioRoutingManager.getPreferOutputDeviceForRendererInfo(rendererInfo).then((desc: audio.AudioDeviceDescriptors) => { 676 console.info(`device descriptor: ${desc}`); 677 }).catch((err: BusinessError) => { 678 console.error(`Result ERROR: ${err}`); 679 }) 680} 681``` 682 683## getPreferredOutputDeviceForRendererInfoSync<sup>10+</sup> 684getPreferredOutputDeviceForRendererInfoSync(rendererInfo: AudioRendererInfo): AudioDeviceDescriptors 685 686Obtains the output device with the highest priority based on the audio renderer information. This API returns the result synchronously. 687 688**System capability**: SystemCapability.Multimedia.Audio.Device 689 690**Parameters** 691 692| Name | Type | Mandatory| Description | 693| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 694| rendererInfo | [AudioRendererInfo](arkts-apis-audio-i.md#audiorendererinfo8) | Yes | Audio renderer information. | 695 696**Return value** 697 698| Type | Description | 699| --------------------- | --------------------------- | 700| [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | Information about the output device with the highest priority.| 701 702**Error codes** 703 704For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 705 706| ID| Error Message | 707| ------- |--------------------------| 708| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 709| 6800101 | Parameter verification failed. | 710 711**Example** 712 713```ts 714import { audio } from '@kit.AudioKit'; 715import { BusinessError } from '@kit.BasicServicesKit'; 716 717let rendererInfo: audio.AudioRendererInfo = { 718 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music. Set this parameter based on the service scenario. 719 rendererFlags: 0 // AudioRenderer flag. 720}; 721 722try { 723 let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredOutputDeviceForRendererInfoSync(rendererInfo); 724 console.info(`device descriptor: ${desc}`); 725} catch (err) { 726 let error = err as BusinessError; 727 console.error(`Result ERROR: ${error}`); 728} 729``` 730 731## on('preferOutputDeviceChangeForRendererInfo')<sup>10+</sup> 732 733on(type: 'preferOutputDeviceChangeForRendererInfo', rendererInfo: AudioRendererInfo, callback: Callback<AudioDeviceDescriptors\>): void 734 735Subscribes to the change event of the output device with the highest priority, which is triggered when the output device with the highest priority is changed. This API uses an asynchronous callback to return the result. 736 737**System capability**: SystemCapability.Multimedia.Audio.Device 738 739**Parameters** 740 741| Name | Type | Mandatory| Description | 742| :------- | :--------------------------------------------------- | :--- |:--------------------------------------------------------| 743| type | string | Yes | Event type. The event **'preferOutputDeviceChangeForRendererInfo'** is triggered when the output device with the highest priority is changed.| 744| rendererInfo | [AudioRendererInfo](arkts-apis-audio-i.md#audiorendererinfo8) | Yes | Audio renderer information. | 745| callback | Callback<[AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors)\> | Yes | Callback used to return the information about the output device with the highest priority.| 746 747**Error codes** 748 749For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 750 751| ID| Error Message| 752| ------- | --------------------------------------------| 753| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 754| 6800101 | Parameter verification failed. | 755 756**Example** 757 758```ts 759import { audio } from '@kit.AudioKit'; 760 761let rendererInfo: audio.AudioRendererInfo = { 762 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music. Set this parameter based on the service scenario. 763 rendererFlags: 0 // AudioRenderer flag. 764}; 765 766audioRoutingManager.on('preferOutputDeviceChangeForRendererInfo', rendererInfo, (desc: audio.AudioDeviceDescriptors) => { 767 console.info(`device descriptor: ${desc}`); 768}); 769``` 770 771## off('preferOutputDeviceChangeForRendererInfo')<sup>10+</sup> 772 773off(type: 'preferOutputDeviceChangeForRendererInfo', callback?: Callback<AudioDeviceDescriptors\>): void 774 775Unsubscribes from the change event of the output device with the highest priority. This API uses an asynchronous callback to return the result. 776 777**System capability**: SystemCapability.Multimedia.Audio.Device 778 779**Parameters** 780 781| Name | Type | Mandatory| Description | 782| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 783| type | string | Yes | Event type. The event **'preferOutputDeviceChangeForRendererInfo'** is triggered when the output device with the highest priority is changed.| 784| callback | Callback<[AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors)> | No | Callback used to return the information about the output device with the highest priority.| 785 786**Error codes** 787 788For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 789 790| ID| Error Message| 791| ------- | --------------------------------------------| 792| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 793| 6800101 | Parameter verification failed. | 794 795**Example** 796 797```ts 798// Cancel all subscriptions to the event. 799audioRoutingManager.off('preferOutputDeviceChangeForRendererInfo'); 800 801// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 802let preferOutputDeviceChangeForRendererInfoCallback = (desc: audio.AudioDeviceDescriptors) => { 803 console.info(`device descriptor: ${desc}`); 804}; 805let rendererInfo: audio.AudioRendererInfo = { 806 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music. Set this parameter based on the service scenario. 807 rendererFlags: 0 // AudioRenderer flag. 808}; 809 810audioRoutingManager.on('preferOutputDeviceChangeForRendererInfo', rendererInfo, preferOutputDeviceChangeForRendererInfoCallback); 811 812audioRoutingManager.off('preferOutputDeviceChangeForRendererInfo', preferOutputDeviceChangeForRendererInfoCallback); 813``` 814 815## getPreferredInputDeviceForCapturerInfo<sup>10+</sup> 816 817getPreferredInputDeviceForCapturerInfo(capturerInfo: AudioCapturerInfo, callback: AsyncCallback<AudioDeviceDescriptors>): void 818 819Obtains the input device with the highest priority based on the audio capturer information. This API uses an asynchronous callback to return the result. 820 821**System capability**: SystemCapability.Multimedia.Audio.Device 822 823**Parameters** 824 825| Name | Type | Mandatory| Description | 826| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 827| capturerInfo | [AudioCapturerInfo](arkts-apis-audio-i.md#audiocapturerinfo8) | Yes | Audio capturer information. | 828| callback | AsyncCallback<[AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the input device with the highest priority obtained; otherwise, **err** is an error object.| 829 830**Error codes** 831 832For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 833 834| ID| Error Message| 835| ------- | --------------------------------------------| 836| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 837| 6800101 | Parameter verification failed. Return by callback.| 838| 6800301 | System error. Return by callback. | 839 840**Example** 841```ts 842import { audio } from '@kit.AudioKit'; 843import { BusinessError } from '@kit.BasicServicesKit'; 844 845let capturerInfo: audio.AudioCapturerInfo = { 846 source: audio.SourceType.SOURCE_TYPE_MIC, // Audio source type: microphone. Set this parameter based on the service scenario. 847 capturerFlags: 0 // AudioCapturer flag. 848}; 849 850audioRoutingManager.getPreferredInputDeviceForCapturerInfo(capturerInfo, (err: BusinessError, desc: audio.AudioDeviceDescriptors) => { 851 if (err) { 852 console.error(`Result ERROR: ${err}`); 853 } else { 854 console.info(`device descriptor: ${desc}`); 855 } 856}); 857``` 858 859## getPreferredInputDeviceForCapturerInfo<sup>10+</sup> 860 861getPreferredInputDeviceForCapturerInfo(capturerInfo: AudioCapturerInfo): Promise<AudioDeviceDescriptors> 862 863Obtains the input device with the highest priority based on the audio capturer information. This API uses a promise to return the result. 864 865**System capability**: SystemCapability.Multimedia.Audio.Device 866 867**Parameters** 868 869| Name | Type | Mandatory| Description | 870| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 871| capturerInfo | [AudioCapturerInfo](arkts-apis-audio-i.md#audiocapturerinfo8) | Yes | Audio capturer information. | 872 873**Return value** 874 875| Type | Description | 876| --------------------- | --------------------------- | 877| Promise<[AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors)> | Promise used to return the information about the input device with the highest priority.| 878 879**Error codes** 880 881For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 882 883| ID| Error Message| 884| ------- | --------------------------------------------| 885| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 886| 6800101 | Parameter verification failed. Return by promise. | 887| 6800301 | System error. Return by promise. | 888 889**Example** 890 891```ts 892import { audio } from '@kit.AudioKit'; 893import { BusinessError } from '@kit.BasicServicesKit'; 894 895let capturerInfo: audio.AudioCapturerInfo = { 896 source: audio.SourceType.SOURCE_TYPE_MIC, // Audio source type: microphone. Set this parameter based on the service scenario. 897 capturerFlags: 0 // AudioCapturer flag. 898}; 899 900audioRoutingManager.getPreferredInputDeviceForCapturerInfo(capturerInfo).then((desc: audio.AudioDeviceDescriptors) => { 901 console.info(`device descriptor: ${desc}`); 902}).catch((err: BusinessError) => { 903 console.error(`Result ERROR: ${err}`); 904}); 905``` 906 907## getPreferredInputDeviceForCapturerInfoSync<sup>10+</sup> 908 909getPreferredInputDeviceForCapturerInfoSync(capturerInfo: AudioCapturerInfo): AudioDeviceDescriptors 910 911Obtains the input device with the highest priority based on the audio capturer information. This API returns the result synchronously. 912 913**System capability**: SystemCapability.Multimedia.Audio.Device 914 915**Parameters** 916 917| Name | Type | Mandatory| Description | 918| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 919| capturerInfo | [AudioCapturerInfo](arkts-apis-audio-i.md#audiocapturerinfo8) | Yes | Audio capturer information. | 920 921**Return value** 922 923| Type | Description | 924| --------------------- | --------------------------- | 925| [AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors) | Information about the input device with the highest priority.| 926 927**Error codes** 928 929For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 930 931| ID| Error Message| 932| ------- | --------------------------------------------| 933| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 934| 6800101 | Parameter verification failed. | 935 936**Example** 937 938```ts 939import { audio } from '@kit.AudioKit'; 940import { BusinessError } from '@kit.BasicServicesKit'; 941 942let capturerInfo: audio.AudioCapturerInfo = { 943 source: audio.SourceType.SOURCE_TYPE_MIC, // Audio source type: microphone. Set this parameter based on the service scenario. 944 capturerFlags: 0 // AudioCapturer flag. 945}; 946 947try { 948 let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredInputDeviceForCapturerInfoSync(capturerInfo); 949 console.info(`device descriptor: ${desc}`); 950} catch (err) { 951 let error = err as BusinessError; 952 console.error(`Result ERROR: ${error}`); 953} 954``` 955 956## on('preferredInputDeviceChangeForCapturerInfo')<sup>10+</sup> 957 958on(type: 'preferredInputDeviceChangeForCapturerInfo', capturerInfo: AudioCapturerInfo, callback: Callback<AudioDeviceDescriptors\>): void 959 960Subscribes to the change event of the input device with the highest priority, which is triggered when the input device with the highest priority is changed. This API uses an asynchronous callback to return the result. 961 962**System capability**: SystemCapability.Multimedia.Audio.Device 963 964**Parameters** 965 966| Name | Type | Mandatory| Description | 967| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 968| type | string | Yes | Event type. The event **'preferredInputDeviceChangeForCapturerInfo'** is triggered when the input device with the highest priority is changed.| 969| capturerInfo | [AudioCapturerInfo](arkts-apis-audio-i.md#audiocapturerinfo8) | Yes | Audio capturer information. | 970| callback | Callback<[AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors)\> | Yes | Callback used to return the information about the input device with the highest priority.| 971 972**Error codes** 973 974For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 975 976| ID| Error Message| 977| ------- | --------------------------------------------| 978| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 979| 6800101 | Parameter verification failed. | 980 981**Example** 982 983```ts 984import { audio } from '@kit.AudioKit'; 985 986let capturerInfo: audio.AudioCapturerInfo = { 987 source: audio.SourceType.SOURCE_TYPE_MIC, // Audio source type: microphone. Set this parameter based on the service scenario. 988 capturerFlags: 0 // AudioCapturer flag. 989}; 990 991audioRoutingManager.on('preferredInputDeviceChangeForCapturerInfo', capturerInfo, (desc: audio.AudioDeviceDescriptors) => { 992 console.info(`device descriptor: ${desc}`); 993}); 994``` 995 996## off('preferredInputDeviceChangeForCapturerInfo')<sup>10+</sup> 997 998off(type: 'preferredInputDeviceChangeForCapturerInfo', callback?: Callback<AudioDeviceDescriptors\>): void 999 1000Unsubscribes from the change event of the input device with the highest priority. This API uses an asynchronous callback to return the result. 1001 1002**System capability**: SystemCapability.Multimedia.Audio.Device 1003 1004**Parameters** 1005 1006| Name | Type | Mandatory| Description | 1007| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 1008| type | string | Yes | Event type. The event **'preferredInputDeviceChangeForCapturerInfo'** is triggered when the input device with the highest priority is changed.| 1009| callback | Callback<[AudioDeviceDescriptors](arkts-apis-audio-t.md#audiodevicedescriptors)> | No | Callback used to return the information about the input device with the highest priority.| 1010 1011**Error codes** 1012 1013For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 1014 1015| ID| Error Message| 1016| ------- | --------------------------------------------| 1017| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1018| 6800101 | Parameter verification failed. | 1019 1020**Example** 1021 1022```ts 1023// Cancel all subscriptions to the event. 1024audioRoutingManager.off('preferredInputDeviceChangeForCapturerInfo'); 1025 1026// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 1027let preferredInputDeviceChangeForCapturerInfoCallback = (desc: audio.AudioDeviceDescriptors) => { 1028 console.info(`device descriptor: ${desc}`); 1029}; 1030let capturerInfo: audio.AudioCapturerInfo = { 1031 source: audio.SourceType.SOURCE_TYPE_MIC, // Audio source type: microphone. Set this parameter based on the service scenario. 1032 capturerFlags: 0 // AudioCapturer flag. 1033}; 1034 1035audioRoutingManager.on('preferredInputDeviceChangeForCapturerInfo', capturerInfo, preferredInputDeviceChangeForCapturerInfoCallback); 1036 1037audioRoutingManager.off('preferredInputDeviceChangeForCapturerInfo', preferredInputDeviceChangeForCapturerInfoCallback); 1038``` 1039