1# Interface (AudioSessionManager) 2<!--Kit: Audio Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @songshenke--> 5<!--Designer: @caixuejiang; @hao-liangfei; @zhanganxiang--> 6<!--Tester: @Filger--> 7<!--Adviser: @zengyawen--> 8 9> **说明：** 10> 11> - 本模块首批接口从API version 7开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12> - 本Interface首批接口从API version 12开始支持。 13 14音频会话管理。 15 16在使用AudioSessionManager的接口之前，需先通过[getSessionManager](arkts-apis-audio-AudioManager.md#getsessionmanager12)获取AudioSessionManager实例。 17 18## 导入模块 19 20```ts 21import { audio } from '@kit.AudioKit'; 22``` 23 24## activateAudioSession<sup>12+</sup> 25 26activateAudioSession(strategy: AudioSessionStrategy): Promise\<void> 27 28激活音频会话。使用Promise异步回调。 29 30**系统能力：** SystemCapability.Multimedia.Audio.Core 31 32**参数：** 33 34| 参数名 | 类型 | 必填 | 说明 | 35| ------ |-------------------------------------------------| ---- | ------------ | 36| strategy | [AudioSessionStrategy](arkts-apis-audio-i.md#audiosessionstrategy12) | 是 | 音频会话策略。 | 37 38**返回值：** 39 40| 类型 | 说明 | 41| -------------- | ------------------------- | 42| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 43 44**错误码：** 45 46以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 47 48| 错误码ID | 错误信息 | 49| ------- | ---------------------------------------------| 50| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified. 2.Incorrect parameter types. | 51| 6800101 | Parameter verification failed.| 52| 6800301 | System error. Returned by promise. | 53 54**示例：** 55 56```ts 57import { BusinessError } from '@kit.BasicServicesKit'; 58 59let strategy: audio.AudioSessionStrategy = { 60 concurrencyMode: audio.AudioConcurrencyMode.CONCURRENCY_MIX_WITH_OTHERS 61}; 62 63audioSessionManager.activateAudioSession(strategy).then(() => { 64 console.info('activateAudioSession SUCCESS'); 65}).catch((err: BusinessError) => { 66 console.error(`ERROR: ${err}`); 67}); 68``` 69 70## deactivateAudioSession<sup>12+</sup> 71 72deactivateAudioSession(): Promise\<void> 73 74停用音频会话。使用Promise异步回调。 75 76**系统能力：** SystemCapability.Multimedia.Audio.Core 77 78**返回值：** 79 80| 类型 | 说明 | 81| -------------- | ------------------------- | 82| Promise\<void> | Promise对象。无返回结果的Promise对象。 | 83 84**错误码：** 85 86以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 87 88| 错误码ID | 错误信息 | 89| ------- | ---------------------------------------------| 90| 6800301 | System error. Returned by promise. | 91 92**示例：** 93 94```ts 95import { BusinessError } from '@kit.BasicServicesKit'; 96 97audioSessionManager.deactivateAudioSession().then(() => { 98 console.info('deactivateAudioSession SUCCESS'); 99}).catch((err: BusinessError) => { 100 console.error(`ERROR: ${err}`); 101}); 102``` 103 104## isAudioSessionActivated<sup>12+</sup> 105 106isAudioSessionActivated(): boolean 107 108检查音频会话是否已激活。 109 110**系统能力：** SystemCapability.Multimedia.Audio.Core 111 112**返回值：** 113 114| 类型 | 说明 | 115| ------------------------------------------------- |---------------------------------------| 116| boolean | 音频会话是否处于激活状态。true表示已激活，false表示已停用。 | 117 118**示例：** 119 120```ts 121let isActivated = audioSessionManager.isAudioSessionActivated(); 122``` 123 124## on('audioSessionDeactivated')<sup>12+</sup> 125 126on(type: 'audioSessionDeactivated', callback: Callback\<AudioSessionDeactivatedEvent>): void 127 128监听音频会话停用事件（当音频会话停用时触发）。使用callback异步回调。 129 130**系统能力：** SystemCapability.Multimedia.Audio.Core 131 132**参数：** 133 134| 参数名 | 类型 | 必填 | 说明 | 135| -------- |---------------------------------------------------------------------------| ---- | ------------------------------------------------------------ | 136| type | string | 是 | 事件回调类型，支持的事件为'audioSessionDeactivated'，当音频会话停用时，触发该事件。 | 137| callback | Callback<[AudioSessionDeactivatedEvent](arkts-apis-audio-i.md#audiosessiondeactivatedevent12)> | 是 | 回调函数，返回音频会话停用原因。 | 138 139**错误码：** 140 141以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 142 143| 错误码ID | 错误信息 | 144| ------- | --------------------------------------------| 145| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified. 2.Incorrect parameter types. | 146| 6800101 | Parameter verification failed. | 147 148**示例：** 149 150```ts 151audioSessionManager.on('audioSessionDeactivated', (audioSessionDeactivatedEvent: audio.AudioSessionDeactivatedEvent) => { 152 console.info(`reason of audioSessionDeactivated: ${audioSessionDeactivatedEvent.reason} `); 153}); 154``` 155 156## off('audioSessionDeactivated')<sup>12+</sup> 157 158off(type: 'audioSessionDeactivated', callback?: Callback\<AudioSessionDeactivatedEvent>): void 159 160取消监听音频会话停用事件。使用callback异步回调。 161 162**系统能力：** SystemCapability.Multimedia.Audio.Core 163 164**参数：** 165 166| 参数名 | 类型 | 必填 | 说明 | 167| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 168| type | string | 是 | 事件回调类型，支持的事件为'audioSessionDeactivated'，当取消监听音频会话停用事件时，触发该事件。 | 169| callback |Callback<[AudioSessionDeactivatedEvent](arkts-apis-audio-i.md#audiosessiondeactivatedevent12)> | 否 | 回调函数，返回音频会话停用原因。 | 170 171**错误码：** 172 173以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 174 175| 错误码ID | 错误信息 | 176| ------- | --------------------------------------------| 177| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 178| 6800101 | Parameter verification failed. | 179 180**示例：** 181 182```ts 183// 取消该事件的所有监听。 184audioSessionManager.off('audioSessionDeactivated'); 185 186// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 187let audioSessionDeactivatedCallback = (audioSessionDeactivatedEvent: audio.AudioSessionDeactivatedEvent) => { 188 console.info(`reason of audioSessionDeactivated: ${audioSessionDeactivatedEvent.reason} `); 189}; 190 191audioSessionManager.on('audioSessionDeactivated', audioSessionDeactivatedCallback); 192 193audioSessionManager.off('audioSessionDeactivated', audioSessionDeactivatedCallback); 194``` 195 196## setAudioSessionScene<sup>20+</sup> 197 198setAudioSessionScene(scene: AudioSessionScene): void 199 200设置音频会话场景参数。 201 202**系统能力：** SystemCapability.Multimedia.Audio.Core 203 204**参数：** 205 206| 参数名 | 类型 | 必填 | 说明 | 207| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 208| scene | [AudioSessionScene](arkts-apis-audio-e.md#audiosessionscene20) | 是 | 音频会话场景。 | 209 210**错误码：** 211 212以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 213 214| 错误码ID | 错误信息 | 215| ------- | ---------------------------------------------| 216| 6800101 | Parameter verification failed. | 217| 6800103 | Operation not permit at current state.| 218| 6800301 | Audio client call audio service error, System error. | 219 220**示例：** 221 222```ts 223audioSessionManager.setAudioSessionScene(audio.AudioSessionScene.AUDIO_SESSION_SCENE_MEDIA); 224``` 225 226## on('audioSessionStateChanged')<sup>20+</sup> 227 228on(type: 'audioSessionStateChanged', callback: Callback\<AudioSessionStateChangedEvent>): void 229 230监听音频会话状态变更事件（当音频会话焦点变更时触发）。使用callback异步回调。 231 232**系统能力：** SystemCapability.Multimedia.Audio.Core 233 234**参数：** 235 236| 参数名 | 类型 | 必填 | 说明 | 237| -------- |---------------------------------------------------------------------------| ---- | ------------------------------------------------------------ | 238| type | string | 是 | 事件回调类型，支持的事件为'audioSessionStateChanged'，当音频会话状态变更时，触发该事件。 | 239| callback | Callback<[AudioSessionStateChangedEvent](arkts-apis-audio-i.md#audiosessionstatechangedevent20)> | 是 | 回调函数，返回音频会话变更提示信息。 | 240 241**错误码：** 242 243以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 244 245| 错误码ID | 错误信息 | 246| ------- | --------------------------------------------| 247| 6800101 | Parameter verification failed. | 248| 6800102 | Allocate memory failed. | 249| 6800301 | Audio client call audio service error, System error. | 250 251**示例：** 252 253```ts 254audioSessionManager.on('audioSessionStateChanged', (audioSessionStateChangedEvent: audio.AudioSessionStateChangedEvent) => { 255 console.info(`hint of audioSessionStateChanged: ${audioSessionStateChangedEvent.stateChangeHint} `); 256}); 257``` 258 259## off('audioSessionStateChanged')<sup>20+</sup> 260 261off(type: 'audioSessionStateChanged', callback?: Callback\<AudioSessionStateChangedEvent>): void 262 263取消监听音频会话状态变更事件。使用callback异步回调。 264 265**系统能力：** SystemCapability.Multimedia.Audio.Core 266 267**参数：** 268 269| 参数名 | 类型 | 必填 | 说明 | 270| -------- |---------------------------------------------------------------------------| ---- | ------------------------------------------------------------ | 271| type | string | 是 | 事件回调类型，支持的事件为'audioSessionStateChanged'，当音频会话状态变更时，触发该事件。 | 272| callback | Callback<[AudioSessionStateChangedEvent](arkts-apis-audio-i.md#audiosessionstatechangedevent20)> | 否 | 回调函数，返回音频会话变更提示信息。 | 273 274**错误码：** 275 276以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 277 278| 错误码ID | 错误信息 | 279| ------- | --------------------------------------------| 280| 6800101 | Parameter verification failed. | 281| 6800301 | Audio client call audio service error, System error. | 282 283**示例：** 284 285```ts 286// 取消该事件的所有监听。 287audioSessionManager.off('audioSessionStateChanged'); 288 289// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 290let audioSessionStateChangedCallback = (audioSessionStateChangedEvent: audio.AudioSessionStateChangedEvent) => { 291 console.info(`hint of audioSessionStateChanged: ${audioSessionStateChangedEvent.stateChangeHint} `); 292}; 293 294audioSessionManager.on('audioSessionStateChanged', audioSessionStateChangedCallback); 295 296audioSessionManager.off('audioSessionStateChanged', audioSessionStateChangedCallback); 297``` 298 299## setDefaultOutputDevice<sup>20+</sup> 300 301setDefaultOutputDevice(deviceType: DeviceType): Promise<void> 302 303设置默认发声设备。使用Promise方式进行异步回调。 304 305> **说明：** 306> 307> - 本接口适用于以下情况：当设置的[AudioSessionScene](arkts-apis-audio-e.md#audiosessionscene20)为VoIP场景时，激活AudioSession后立即生效。若[AudioSessionScene](arkts-apis-audio-e.md#audiosessionscene20)为非VoIP场景，激活AudioSession时不会生效，仅在启动播放的[StreamUsage](arkts-apis-audio-e.md#streamusage)为语音消息、VoIP语音通话或VoIP视频通话时才生效。支持听筒、扬声器和系统默认设备。 308> 309> - 本接口允许在AudioSessionManager创建后随时调用，系统会记录应用设置的默认本机内置发声设备。但只有激活AudioSession后才能生效。应用启动播放时，若外接设备如蓝牙耳机或有线耳机已接入，系统优先从外接设备发声。否则，系统遵循应用设置的默认本机内置发声设备。 310> 311> - 本接口优先级低于[AVCastPicker](../apis-avsession-kit/ohos-multimedia-avcastpicker.md#avcastpicker)。如果使用AVCastPicker切换过发声设备，再次调用本接口将不生效。 312 313**系统能力：** SystemCapability.Multimedia.Audio.Device 314 315**参数：** 316 317| 参数名 | 类型 | 必填 | 说明 | 318| ---------- |----------------| ------ |---------------------------------------------------------| 319| deviceType | [DeviceType](arkts-apis-audio-e.md#devicetype) | 是 | 设备类型。<br>仅支持以下设备：EARPIECE（听筒）、SPEAKER（扬声器）和DEFAULT（系统默认设备）。 | 320 321**返回值：** 322 323| 类型 | 说明 | 324| ------------------- | ----------------------------- | 325| Promise<void> | Promise对象。无返回结果的Promise对象。 | 326 327**错误码：** 328 329以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 330 331| 错误码ID | 错误信息 | 332| ------- | --------------------------------------------| 333| 6800101 | Parameter verification failed. Return by promise. | 334| 6800102 | Allocate memory failed. Return by promise. | 335| 6800301 | Audio client call audio service error, System error. | 336 337**示例：** 338 339```ts 340import { BusinessError } from '@kit.BasicServicesKit'; 341 342audioSessionManager.setDefaultOutputDevice(audio.DeviceType.SPEAKER).then(() => { 343 console.info('setDefaultOutputDevice Success!'); 344}).catch((err: BusinessError) => { 345 console.error(`setDefaultOutputDevice Fail: ${err}`); 346}); 347``` 348 349## getDefaultOutputDevice<sup>20+</sup> 350 351getDefaultOutputDevice(): DeviceType 352 353获取通过[setDefaultOutputDevice](#setdefaultoutputdevice20)设置的默认发声设备。 354 355**系统能力：** SystemCapability.Multimedia.Audio.Device 356 357**返回值：** 358 359| 类型 | 说明 | 360| ------------------------------------------------- |---------------------------------------| 361| DeviceType |设备类型。<br>仅支持以下设备：EARPIECE（听筒）、SPEAKER（扬声器）和DEFAULT（系统默认设备）。 | 362 363**错误码：** 364 365以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 366 367| 错误码ID | 错误信息 | 368|---------| --------------------------------------------| 369| 6800101 | Parameter verification failed. | 370| 6800103 | Operation not permit at current state. Return by promise. | 371 372**示例：** 373 374```ts 375let deviceType = audioSessionManager.getDefaultOutputDevice(); 376``` 377 378## on('currentOutputDeviceChanged')<sup>20+</sup> 379 380on(type: 'currentOutputDeviceChanged', callback: Callback\<CurrentOutputDeviceChangedEvent>): void 381 382监听当前输出设备变化事件（当前输出设备发生变化时触发）。使用callback异步回调。 383 384**系统能力：** SystemCapability.Multimedia.Audio.Device 385 386**参数：** 387 388| 参数名 | 类型 | 必填 | 说明 | 389| :------- | :--------------------------------------------------- | :--- |:--------------------------------------------------------| 390| type | string | 是 | 事件回调类型，支持的事件为'currentOutputDeviceChanged'，当前输出设备变更时触发。| 391| callback | Callback<[CurrentOutputDeviceChangedEvent](arkts-apis-audio-i.md#currentoutputdevicechangedevent20)> | 是 | 回调函数，返回当前输出设备信息。 | 392 393**错误码：** 394 395以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md)。 396 397| 错误码ID | 错误信息 | 398| ------- | --------------------------------------------| 399| 6800101 | Parameter verification failed. | 400| 6800102 | Allocate memory failed. | 401| 6800301 | Audio client call audio service error, System error. | 402 403**示例：** 404 405```ts 406import { audio } from '@kit.AudioKit'; 407 408let currentOutputDeviceChangedCallback = (currentOutputDeviceChangedEvent: audio.CurrentOutputDeviceChangedEvent) => { 409 console.info(`reason of audioSessionStateChanged: ${currentOutputDeviceChangedEvent.changeReason} `); 410}; 411 412audioSessionManager.on('currentOutputDeviceChanged', currentOutputDeviceChangedCallback); 413``` 414 415## off('currentOutputDeviceChanged')<sup>20+</sup> 416 417off(type: 'currentOutputDeviceChanged', callback?: Callback\<CurrentOutputDeviceChangedEvent>): void 418 419取消监听当前输出设备的变化事件，并使用callback进行异步回调。 420 421**系统能力：** SystemCapability.Multimedia.Audio.Device 422 423**参数：** 424 425| 参数名 | 类型 | 必填 | 说明 | 426| :------- | :--------------------------------------------------- | :--- |:--------------------------------------------------------| 427| type | string | 是 | 事件回调类型，支持的事件为'currentOutputDeviceChanged'，当前输出设备发生变化时，触发该事件。| 428| callback | Callback<[CurrentOutputDeviceChangedEvent](arkts-apis-audio-i.md#currentoutputdevicechangedevent20)> | 否 | 回调函数，用于返回当前输出设备变化的信息。 | 429 430**错误码：** 431 432以下错误码的详细介绍请参见[Audio错误码](errorcode-audio.md) 433 434| 错误码ID | 错误信息 | 435| ------- | --------------------------------------------| 436| 6800101 | Parameter verification failed. | 437| 6800301 | Audio client call audio service error, System error. | 438 439**示例：** 440 441```ts 442// 取消该事件的所有监听。 443audioSessionManager.off('currentOutputDeviceChanged'); 444 445// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 446let currentOutputDeviceChangedCallback = (currentOutputDeviceChangedEvent: audio.CurrentOutputDeviceChangedEvent) => { 447 console.info(`reason of audioSessionStateChanged: ${currentOutputDeviceChangedEvent.changeReason} `); 448}; 449 450audioSessionManager.on('currentOutputDeviceChanged', currentOutputDeviceChangedCallback); 451 452audioSessionManager.off('currentOutputDeviceChanged', currentOutputDeviceChangedCallback); 453``` 454