1# @ohos.multimedia.avsession (AVSession Management) (System API) 2 3The avSession module provides APIs for media playback control so that applications can access the system's Media Controller. 4 5This module provides the following typical features related to media sessions: 6 7- [AVCastController](#avcastcontroller10): used to control playback, listen for remote playback state changes, and obtain the remote playback state in casting scenarios. 8 9> **NOTE** 10> 11> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. 12> - This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.multimedia.avsession (AVSession Management)](js-apis-avsession.md). 13 14## Modules to Import 15 16```ts 17import { avSession } from '@kit.AVSessionKit'; 18``` 19 20## Usage Guidelines 21 22This topic describes only system APIs. Before using these APIs, you must create an instance. For details about how to create an instance, see the description and example of the public API [avSession.createAVSession](js-apis-avsession.md#avsessioncreateavsession10). 23 24## avSession.getAllSessionDescriptors 25 26getAllSessionDescriptors(): Promise\<Array\<Readonly\<AVSessionDescriptor>>> 27 28Obtains the descriptors of all sessions that have set media information and registered control callbacks. This API uses a promise to return the result. 29 30**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 31 32**System capability**: SystemCapability.Multimedia.AVSession.Manager 33 34**System API**: This is a system API. 35 36**Return value** 37 38| Type | Description | 39| ------------------------------------------------------------ | --------------------------------------------- | 40| Promise\<Array\<Readonly\<[AVSessionDescriptor](#avsessiondescriptor)\>\>\> | Promise used to return an array of **AVSessionDescriptor** objects, each of which is read only.| 41 42**Error codes** 43 44For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 45 46| ID| Error Message| 47| -------- | ---------------------------------------- | 48| 201 | permission denied. | 49| 6600101 | Session service exception. | 50 51**Example** 52 53```ts 54import { BusinessError } from '@kit.BasicServicesKit'; 55 56avSession.getAllSessionDescriptors().then((descriptors: avSession.AVSessionDescriptor[]) => { 57 console.info(`getAllSessionDescriptors : SUCCESS : descriptors.length : ${descriptors.length}`); 58 if (descriptors.length > 0 ) { 59 console.info(`getAllSessionDescriptors : SUCCESS : descriptors[0].isActive : ${descriptors[0].isActive}`); 60 console.info(`GetAllSessionDescriptors : SUCCESS : descriptors[0].type : ${descriptors[0].type}`); 61 console.info(`GetAllSessionDescriptors : SUCCESS : descriptors[0].sessionTag : ${descriptors[0].sessionTag}`); 62 } 63}).catch((err: BusinessError) => { 64 console.error(`GetAllSessionDescriptors BusinessError: code: ${err.code}, message: ${err.message}`); 65}); 66``` 67 68## avSession.getAllSessionDescriptors 69 70getAllSessionDescriptors(callback: AsyncCallback\<Array\<Readonly\<AVSessionDescriptor>>>): void 71 72Obtains the descriptors of all sessions that have set media information and registered control callbacks. This API uses an asynchronous callback to return the result. 73 74**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES 75 76**System capability**: SystemCapability.Multimedia.AVSession.Manager 77 78**System API**: This is a system API. 79 80**Parameters** 81 82| Name | Type | Mandatory| Description | 83| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | 84| callback | AsyncCallback<Array<Readonly<[AVSessionDescriptor](#avsessiondescriptor)\>\>\> | Yes | Callback used to return an array of **AVSessionDescriptor** objects, each of which is read only.| 85 86**Error codes** 87 88For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 89 90| ID| Error Message| 91| -------- | ---------------------------------------- | 92| 201 | permission denied. | 93| 6600101 |Session service exception. | 94 95**Example** 96 97```ts 98import { BusinessError } from '@kit.BasicServicesKit'; 99 100avSession.getAllSessionDescriptors((err: BusinessError, descriptors: avSession.AVSessionDescriptor[]) => { 101 if (err) { 102 console.error(`GetAllSessionDescriptors BusinessError: code: ${err.code}, message: ${err.message}`); 103 } else { 104 console.info(`GetAllSessionDescriptors : SUCCESS : descriptors.length : ${descriptors.length}`); 105 if (descriptors.length > 0 ) { 106 console.info(`getAllSessionDescriptors : SUCCESS : descriptors[0].isActive : ${descriptors[0].isActive}`); 107 console.info(`getAllSessionDescriptors : SUCCESS : descriptors[0].type : ${descriptors[0].type}`); 108 console.info(`getAllSessionDescriptors : SUCCESS : descriptors[0].sessionTag : ${descriptors[0].sessionTag}`); 109 } 110 } 111}); 112``` 113 114## avSession.getHistoricalSessionDescriptors<sup>10+</sup> 115 116getHistoricalSessionDescriptors(maxSize?: number): Promise\<Array\<Readonly\<AVSessionDescriptor>>> 117 118Obtains the descriptors of all historical sessions. This API uses a promise to return the result. 119 120**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES 121 122**System capability**: SystemCapability.Multimedia.AVSession.Manager 123 124**System API**: This is a system API. 125 126**Parameters** 127 128| Name | Type | Mandatory| Description | 129| -------- | ------ | ---- | -----------------------------------------------------------------| 130| maxSize | number | No | Maximum number of descriptors to obtain. The value ranges from 0 to 10. If this parameter is left blank, the default value **3** is used.| 131 132**Return value** 133 134| Type | Description | 135| --------------------------------------------------------------------------- | -------------------------------------- | 136| Promise\<Array\<Readonly\<[AVSessionDescriptor](#avsessiondescriptor)\>\>\> | Promise used to return an array of **AVSessionDescriptor** objects, each of which is read only.| 137 138**Error codes** 139 140For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 141 142| ID| Error Message| 143| -------- | ---------------------------------------- | 144| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 145| 6600101 | Session service exception. | 146 147**Example** 148 149```ts 150import { BusinessError } from '@kit.BasicServicesKit'; 151 152avSession.getHistoricalSessionDescriptors().then((descriptors: avSession.AVSessionDescriptor[]) => { 153 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors.length : ${descriptors.length}`); 154 if (descriptors.length > 0 ) { 155 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].isActive : ${descriptors[0].isActive}`); 156 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].type : ${descriptors[0].type}`); 157 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].sessionTag : ${descriptors[0].sessionTag}`); 158 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].sessionId : ${descriptors[0].sessionId}`); 159 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].elementName.bundleName : ${descriptors[0].elementName.bundleName}`); 160 } 161}).catch((err: BusinessError) => { 162 console.error(`getHistoricalSessionDescriptors BusinessError: code: ${err.code}, message: ${err.message}`); 163}); 164``` 165 166## avSession.getHistoricalSessionDescriptors<sup>10+</sup> 167 168getHistoricalSessionDescriptors(maxSize: number, callback: AsyncCallback\<Array\<Readonly\<AVSessionDescriptor>>>): void 169 170Obtains the descriptors of all historical sessions. This API uses an asynchronous callback to return the result. 171 172**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES 173 174**System capability**: SystemCapability.Multimedia.AVSession.Manager 175 176**System API**: This is a system API. 177 178**Parameters** 179 180| Name | Type | Mandatory| Description | 181| -------- | ------------------------------------------------------------------------------ | ---- | -----------------------------------------------------------------| 182| maxSize | number | Yes | Maximum number of descriptors to obtain. The value ranges from 0 to 10.| 183| callback | AsyncCallback<Array<Readonly<[AVSessionDescriptor](#avsessiondescriptor)\>\>\> | Yes | Callback used to return an array of **AVSessionDescriptor** objects, each of which is read only. | 184 185**Error codes** 186 187For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 188 189| ID| Error Message| 190| -------- | ---------------------------------------- | 191| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 192| 6600101 |Session service exception. | 193 194**Example** 195 196```ts 197import { BusinessError } from '@kit.BasicServicesKit'; 198 199avSession.getHistoricalSessionDescriptors(1, (err: BusinessError, descriptors: avSession.AVSessionDescriptor[]) => { 200 if (err) { 201 console.error(`getHistoricalSessionDescriptors BusinessError: code: ${err.code}, message: ${err.message}`); 202 } else { 203 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors.length : ${descriptors.length}`); 204 if (descriptors.length > 0 ) { 205 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].isActive : ${descriptors[0].isActive}`); 206 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].type : ${descriptors[0].type}`); 207 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].sessionTag : ${descriptors[0].sessionTag}`); 208 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].sessionId : ${descriptors[0].sessionId}`); 209 console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].elementName.bundleName : ${descriptors[0].elementName.bundleName}`); 210 } 211 } 212}); 213``` 214 215## avSession.getHistoricalAVQueueInfos<sup>11+</sup> 216 217getHistoricalAVQueueInfos(maxSize: number, maxAppSize: number) : Promise\<Array\<Readonly\<AVQueueInfo>>> 218 219Obtains all the historical playlists. This API uses a promise to return the result. 220 221**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES 222 223**System capability**: SystemCapability.Multimedia.AVSession.Manager 224 225**System API**: This is a system API. 226 227**Parameters** 228 229| Name | Type | Mandatory| Description | 230| -------- | ------ | ---- | ---------------------------------------------------------------| 231| maxSize | number | Yes | Maximum number of playlists that can be obtained. Currently, the maximum number is restricted by the system. | 232| maxAppSize | number | Yes | Maximum number of applications to which the playlists to be obtained belong. Currently, the maximum number is restricted by the system. | 233 234**Return value** 235 236| Type | Description | 237| --------------------------------------------------------------------------- | ------------------------------------- | 238| Promise\<Array\<Readonly\<[AVQueueInfo](#avqueueinfo11)\>\>\> | Promise used to return all the read-only historical playlists. | 239 240**Error codes** 241 242For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 243 244| ID| Error Message| 245| -------- | ---------------------------------------- | 246| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 247| 6600101 | Session service exception. | 248 249**Example** 250 251```ts 252import { BusinessError } from '@kit.BasicServicesKit'; 253 254avSession.getHistoricalAVQueueInfos(3, 5).then((avQueueInfos: avSession.AVQueueInfo[]) => { 255 console.info(`getHistoricalAVQueueInfos : SUCCESS : avQueueInfos.length : ${avQueueInfos.length}`); 256}).catch((err: BusinessError) => { 257 console.error(`getHistoricalAVQueueInfos BusinessError: code: ${err.code}, message: ${err.message}`); 258}); 259``` 260 261## avSession.getHistoricalAVQueueInfos<sup>11+</sup> 262 263getHistoricalAVQueueInfos(maxSize: number, maxAppSize: number, callback: AsyncCallback\<Array\<Readonly\<AVQueueInfo>>>): void; 264 265Obtains all the historical playlists. This API uses an asynchronous callback to return the result. 266 267**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES 268 269**System capability**: SystemCapability.Multimedia.AVSession.Manager 270 271**System API**: This is a system API. 272 273**Parameters** 274 275| Name | Type | Mandatory| Description | 276| -------- | ----------------------------------------------------------------------------- | ---- | ---------------------------------------------------------------| 277| maxSize | number | Yes | Maximum number of playlists that can be obtained. Currently, the maximum number is restricted by the system. | 278| maxAppSize | number | Yes | Maximum number of applications to which the playlists to be obtained belong. Currently, the maximum number is restricted by the system. | 279| callback | AsyncCallback<Array<Readonly<[AVQueueInfo](#avqueueinfo11)\>\>\> | Yes | Callback used to return all the read-only historical playlists. | 280 281**Error codes** 282 283For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 284 285| ID| Error Message| 286| -------- | ---------------------------------------- | 287| 201 | permission denied. | 288| 202 | Not System App. | 289| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 290| 6600101 |Session service exception. | 291 292**Example** 293 294```ts 295import { BusinessError } from '@kit.BasicServicesKit'; 296 297avSession.getHistoricalAVQueueInfos(3, 5, (err: BusinessError, avQueueInfos: avSession.AVQueueInfo[]) => { 298 if (err) { 299 console.error(`getHistoricalAVQueueInfos BusinessError: code: ${err.code}, message: ${err.message}`); 300 } else { 301 console.info(`getHistoricalAVQueueInfos : SUCCESS : avQueueInfos.length : ${avQueueInfos.length}`); 302 } 303}); 304``` 305 306## avSession.createController 307 308createController(sessionId: string): Promise\<AVSessionController> 309 310Creates a session controller based on the session ID. Multiple session controllers can be created. This API uses a promise to return the result. 311 312**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 313 314**System capability**: SystemCapability.Multimedia.AVSession.Manager 315 316**System API**: This is a system API. 317 318**Parameters** 319 320| Name | Type | Mandatory| Description | 321| --------- | ------ | ---- | -------- | 322| sessionId | string | Yes | Session ID. If the value is set to **'default'**, the system creates a default controller to control the system default session.| 323 324**Return value** 325 326| Type | Description | 327| ----------------------------------------------------- | ------------------------------------------------------------ | 328| Promise<[AVSessionController](js-apis-avsession.md#avsessioncontroller10)\> | Promise used to return the session controller created, which can be used to obtain the session ID,<br>send commands and events to sessions, and obtain metadata and playback state information.| 329 330**Error codes** 331 332For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 333 334| ID| Error Message| 335| -------- | ---------------------------------------- | 336| 201 | permission denied. | 337| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 338| 6600101 | Session service exception. | 339| 6600102 | The session does not exist. | 340 341**Example** 342 343```ts 344import { BusinessError } from '@kit.BasicServicesKit'; 345 346let currentAVcontroller: avSession.AVSessionController | undefined = undefined; 347currentAvSession.createController(sessionId).then((avcontroller: avSession.AVSessionController) => { 348 currentAVcontroller = avcontroller; 349 console.info('CreateController : SUCCESS '); 350}).catch((err: BusinessError) => { 351 console.error(`CreateController BusinessError: code: ${err.code}, message: ${err.message}`); 352}); 353``` 354 355## avSession.createController 356 357createController(sessionId: string, callback: AsyncCallback\<AVSessionController>): void 358 359Creates a session controller based on the session ID. Multiple session controllers can be created. This API uses an asynchronous callback to return the result. 360 361**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 362 363**System capability**: SystemCapability.Multimedia.AVSession.Manager 364 365**System API**: This is a system API. 366 367**Parameters** 368 369| Name | Type | Mandatory| Description | 370| --------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 371| sessionId | string | Yes | Session ID. If the value is set to **'default'**, the system creates a default controller to control the system default session. | 372| callback | AsyncCallback<[AVSessionController](js-apis-avsession.md#avsessioncontroller10)\> | Yes | Callback used to return the session controller created, which can be used to obtain the session ID,<br>send commands and events to sessions, and obtain metadata and playback state information.| 373 374**Error codes** 375 376For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 377 378| ID| Error Message| 379| -------- | ---------------------------------------- | 380| 201 | permission denied. | 381| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 382| 6600101 | Session service exception. | 383| 6600102 | The session does not exist. | 384 385**Example** 386 387```ts 388import { BusinessError } from '@kit.BasicServicesKit'; 389 390let currentAVcontroller: avSession.AVSessionController | undefined = undefined; 391currentAvSession.createController(sessionId, (err: BusinessError, avcontroller: avSession.AVSessionController) => { 392 if (err) { 393 console.error(`CreateController BusinessError: code: ${err.code}, message: ${err.message}`); 394 } else { 395 currentAVcontroller = avcontroller; 396 console.info('CreateController : SUCCESS '); 397 } 398}); 399``` 400 401## avSession.castAudio 402 403castAudio(session: SessionToken | 'all', audioDevices: Array<audio.AudioDeviceDescriptor>): Promise\<void> 404 405Casts a session to a list of devices. This API uses a promise to return the result. 406 407Before calling this API, import the **ohos.multimedia.audio** module to obtain the descriptors of these audio devices. 408 409**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 410 411**System capability**: SystemCapability.Multimedia.AVSession.Manager 412 413**System API**: This is a system API. 414 415**Parameters** 416 417| Name | Type | Mandatory| Description| 418| ------------ | -------------- |------|------| 419| session | [SessionToken](#sessiontoken) | 'all' | Yes | Session token. **SessionToken** indicates a specific token, and **'all'** indicates all tokens.| 420| audioDevices | Array\<[audio.AudioDeviceDescriptor](../apis-audio-kit/js-apis-audio.md#audiodevicedescriptor)\> | Yes | Audio devices. | 421 422**Return value** 423 424| Type | Description | 425| -------------- | ----------------------------- | 426| Promise\<void> | Promise used to return the result. If casting is successful, no value is returned; otherwise, an error object is returned.| 427 428**Error codes** 429 430For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 431 432| ID| Error Message| 433| -------- | ---------------------------------------- | 434| 201 | permission denied. | 435| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 436| 6600101 | Session service exception. | 437| 6600102 | The session does not exist. | 438| 6600104 | The remote session connection failed. | 439 440**Example** 441 442```ts 443import { audio } from '@kit.AudioKit'; 444import { BusinessError } from '@kit.BasicServicesKit'; 445 446let audioManager = audio.getAudioManager(); 447let audioRoutingManager = audioManager.getRoutingManager(); 448let audioDevices: audio.AudioDeviceDescriptors | undefined = undefined; 449audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data) => { 450 audioDevices = data; 451 console.info('Promise returned to indicate that the device list is obtained.'); 452}).catch((err: BusinessError) => { 453 console.error(`GetDevices BusinessError: code: ${err.code}, message: ${err.message}`); 454}); 455 456if (audioDevices !== undefined) { 457 avSession.castAudio('all', audioDevices as audio.AudioDeviceDescriptors).then(() => { 458 console.info('CreateController : SUCCESS'); 459 }).catch((err: BusinessError) => { 460 console.error(`CreateController BusinessError: code: ${err.code}, message: ${err.message}`); 461 }); 462} 463``` 464 465## avSession.castAudio 466 467castAudio(session: SessionToken | 'all', audioDevices: Array<audio.AudioDeviceDescriptor>, callback: AsyncCallback\<void>): void 468 469Casts a session to a list of devices. This API uses an asynchronous callback to return the result. 470 471Before calling this API, import the **ohos.multimedia.audio** module to obtain the descriptors of these audio devices. 472 473**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 474 475**System capability**: SystemCapability.Multimedia.AVSession.Manager 476 477**System API**: This is a system API. 478 479**Parameters** 480 481| Name | Type | Mandatory| Description | 482| ------------ |--------------------------------------------| ---- | ------------------------------------------------------------ | 483| session | [SessionToken](#sessiontoken) | 'all' | Yes | Session token. **SessionToken** indicates a specific token, and **'all'** indicates all tokens.| 484| audioDevices | Array\<[audio.AudioDeviceDescriptor](../apis-audio-kit/js-apis-audio.md#audiodevicedescriptor)\> | Yes | Audio devices.| 485| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If casting is successful, **err** is **undefined**; otherwise, **err** is an error object. | 486 487**Error codes** 488 489For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 490 491| ID| Error Message| 492| -------- | ---------------------------------------- | 493| 201 | permission denied. | 494| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 495| 6600101 | Session service exception. | 496| 6600102 | The session does not exist. | 497| 6600104 | The remote session connection failed. | 498 499**Example** 500 501```ts 502import { audio } from '@kit.AudioKit'; 503import { BusinessError } from '@kit.BasicServicesKit'; 504 505let audioManager = audio.getAudioManager(); 506let audioRoutingManager = audioManager.getRoutingManager(); 507let audioDevices: audio.AudioDeviceDescriptors | undefined = undefined; 508audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data) => { 509 audioDevices = data; 510 console.info('Promise returned to indicate that the device list is obtained.'); 511}).catch((err: BusinessError) => { 512 console.error(`GetDevices BusinessError: code: ${err.code}, message: ${err.message}`); 513}); 514 515if (audioDevices !== undefined) { 516 avSession.castAudio('all', audioDevices as audio.AudioDeviceDescriptors, (err: BusinessError) => { 517 if (err) { 518 console.error(`CastAudio BusinessError: code: ${err.code}, message: ${err.message}`); 519 } else { 520 console.info('CastAudio : SUCCESS '); 521 } 522 }); 523} 524``` 525 526## avSession.startAVPlayback<sup>11+</sup> 527 528startAVPlayback(bundleName: string, assetId: string): Promise\<void> 529 530Starts an application to play a media asset. This API uses a promise to return the result. 531 532**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 533 534**System capability**: SystemCapability.Multimedia.AVSession.Manager 535 536**System API**: This is a system API. 537 538**Parameters** 539 540| Name | Type | Mandatory| Description| 541| ------------ | -------------- |------|------| 542| bundleName | string | Yes | Bundle name of the application.| 543| assetId |string | Yes | ID of the media asset. | 544 545**Return value** 546 547| Type | Description | 548| -------------- | ----------------------------- | 549| Promise\<void> | Promise used to return the result. If the playback is successful, no value is returned; otherwise, an error object is returned.| 550 551**Error codes** 552 553For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 554 555| ID| Error Message| 556| -------- | ---------------------------------------- | 557| 201 | permission denied. | 558| 202 | Not System App. Interface caller is not a system app. | 559| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 560| 6600101 | Session service exception. | 561 562**Example** 563 564```ts 565import { audio } from '@kit.AudioKit'; 566import { BusinessError } from '@kit.BasicServicesKit'; 567 568avSession.startAVPlayback("com.example.myapplication", "121278").then(() => { 569 console.info('startAVPlayback : SUCCESS'); 570}).catch((err: BusinessError) => { 571 console.error(`startAVPlayback BusinessError: code: ${err.code}, message: ${err.message}`); 572}); 573``` 574 575## avSession.getDistributedSessionController<sup>18+</sup> 576 577getDistributedSessionController(distributedSessionType: DistributedSessionType): Promise<Array\<AVSessionController>> 578 579Obtains remote distributed session controllers based on the remote session type. This API uses a promise to return the result. 580 581**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES 582 583**System capability**: SystemCapability.Multimedia.AVSession.Manager 584 585**System API**: This is a system API. 586 587**Parameters** 588 589| Name | Type | Mandatory| Description | 590| --------- |-------------------------------------------------------------------------| ---- |---------| 591| distributedSessionType | [DistributedSessionType](js-apis-avsession.md#distributedsessiontype18) | Yes | Remote session type.| 592 593**Return value** 594 595| Type | Description | 596|------------------------------------------------------------------------------------|-----------------------------------------------------------------------| 597| Promise<Array<[AVSessionController](js-apis-avsession.md#avsessioncontroller10)\>> | Promise used to return an array of session controller instances of the corresponding type. You can view the session ID, send commands and events to the session, and obtain metadata and playback status information.| 598 599**Error codes** 600 601For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 602 603| ID | Error Message | 604|---------|-------------------------------------------------------------------------------------------------------| 605| 201 | permission denied. | 606| 202 | Not System App. Interface caller is not a system app. | 607| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 608| 6600101 | Session service exception. | 609| 6600109 | The remote connection is not established. | 610 611**Example** 612 613```ts 614import { BusinessError } from '@kit.BasicServicesKit'; 615 616avSession.getDistributedSessionController(avSession.DistributedSessionType.TYPE_SESSION_REMOTE).then((sessionControllers: Array<avSession.AVSessionController>) => { 617 console.info(`getDistributedSessionController : SUCCESS : sessionControllers.length : ${sessionControllers.length}`); 618}).catch((err: BusinessError) => { 619 console.error(`getDistributedSessionController BusinessError: code: ${err.code}, message: ${err.message}`); 620}); 621``` 622 623 624## SessionToken 625 626Describes the information about a session token. 627 628**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 629 630**System capability**: SystemCapability.Multimedia.AVSession.Manager 631 632**System API**: This is a system API. 633 634| Name | Type | Mandatory| Description | 635| :-------- | :----- | :--- | :----------- | 636| sessionId | string | Yes | Session ID. | 637| pid | number | No | Process ID of the session.| 638| uid | number | No | User ID. | 639 640## avSession.on('sessionCreate') 641 642on(type: 'sessionCreate', callback: (session: AVSessionDescriptor) => void): void 643 644Subscribes to session creation events. 645 646**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 647 648**System capability**: SystemCapability.Multimedia.AVSession.Manager 649 650**System API**: This is a system API. 651 652**Parameters** 653 654| Name | Type | Mandatory| Description | 655| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 656| type | string | Yes | Event type. The event **'sessionCreate'** is triggered when a session is created.| 657| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | Yes | Callback used to report the session descriptor.| 658 659**Error codes** 660 661For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 662 663| ID| Error Message| 664| -------- | ---------------------------------------- | 665| 201 | permission denied. | 666| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 667| 6600101 | Session service exception. | 668 669**Example** 670 671```ts 672avSession.on('sessionCreate', (descriptor: avSession.AVSessionDescriptor) => { 673 console.info(`on sessionCreate : isActive : ${descriptor.isActive}`); 674 console.info(`on sessionCreate : type : ${descriptor.type}`); 675 console.info(`on sessionCreate : sessionTag : ${descriptor.sessionTag}`); 676}); 677 678``` 679 680## avSession.on('sessionDestroy') 681 682on(type: 'sessionDestroy', callback: (session: AVSessionDescriptor) => void): void 683 684Subscribes to session destruction events. 685 686**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 687 688**System capability**: SystemCapability.Multimedia.AVSession.Manager 689 690**System API**: This is a system API. 691 692**Parameters** 693 694| Name | Type | Mandatory| Description | 695| -------- | ---------------| ---- | ------------------------------------------------------------ | 696| type | string | Yes | Event type. The event **'sessionDestroy'** is triggered when a session is destroyed.| 697| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | Yes | Callback used to report the session descriptor.| 698 699**Error codes** 700 701For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 702 703| ID| Error Message| 704| -------- | ---------------------------------------- | 705| 201 | permission denied. | 706| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 707| 6600101 | Session service exception. | 708 709**Example** 710 711```ts 712avSession.on('sessionDestroy', (descriptor: avSession.AVSessionDescriptor) => { 713 console.info(`on sessionDestroy : isActive : ${descriptor.isActive}`); 714 console.info(`on sessionDestroy : type : ${descriptor.type}`); 715 console.info(`on sessionDestroy : sessionTag : ${descriptor.sessionTag}`); 716}); 717``` 718 719## avSession.on('topSessionChange') 720 721on(type: 'topSessionChange', callback: (session: AVSessionDescriptor) => void): void 722 723Subscribes to top session change events. 724 725**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 726 727**System capability**: SystemCapability.Multimedia.AVSession.Manager 728 729**System API**: This is a system API. 730 731**Parameters** 732 733| Name | Type | Mandatory| Description | 734| -------- | --------------------| ---- | ------------------------------------------------------------ | 735| type | string | Yes | Event type. The event **'topSessionChange'** is triggered when the top session is changed.| 736| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | Yes | Callback used to report the session descriptor.| 737 738**Error codes** 739 740For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 741 742| ID| Error Message| 743| -------- | ---------------------------------------- | 744| 201 | permission denied. | 745| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 746| 6600101 | Session service exception. | 747 748**Example** 749 750```ts 751avSession.on('topSessionChange', (descriptor: avSession.AVSessionDescriptor) => { 752 console.info(`on topSessionChange : isActive : ${descriptor.isActive}`); 753 console.info(`on topSessionChange : type : ${descriptor.type}`); 754 console.info(`on topSessionChange : sessionTag : ${descriptor.sessionTag}`); 755}); 756``` 757 758## avSession.off('sessionCreate') 759 760off(type: 'sessionCreate', callback?: (session: AVSessionDescriptor) => void): void 761 762Unsubscribes from session creation events. 763 764**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 765 766**System capability**: SystemCapability.Multimedia.AVSession.Manager 767 768**System API**: This is a system API. 769 770**Parameters** 771 772| Name | Type | Mandatory| Description | 773| -------- | ----------| ---- | ----------| 774| type | string | Yes | Event type, which is **'sessionCreate'** in this case.| 775| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.<br>The **session** parameter in the callback describes a media session. The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. | 776 777**Error codes** 778 779For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 780 781| ID| Error Message| 782| -------- | ---------------------------------------- | 783| 201 | permission denied. | 784| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 785| 6600101 | Session service exception. | 786 787**Example** 788 789```ts 790avSession.off('sessionCreate'); 791``` 792 793## avSession.off('sessionDestroy') 794 795off(type: 'sessionDestroy', callback?: (session: AVSessionDescriptor) => void): void 796 797Unsubscribes from session destruction events. 798 799**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 800 801**System capability**: SystemCapability.Multimedia.AVSession.Manager 802 803**System API**: This is a system API. 804 805**Parameters** 806 807| Name | Type | Mandatory| Description | 808| -------- | -----------| ---- | -------------------------| 809| type | string | Yes | Event type, which is **'sessionDestroy'** in this case.| 810| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.<br>The **session** parameter in the callback describes a media session. The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.| 811 812**Error codes** 813 814For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 815 816| ID| Error Message| 817| -------- | ---------------------------------------- | 818| 201 | permission denied. | 819| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 820| 6600101 | Session service exception. | 821 822**Example** 823 824```ts 825avSession.off('sessionDestroy'); 826``` 827 828## avSession.off('topSessionChange') 829 830off(type: 'topSessionChange', callback?: (session: AVSessionDescriptor) => void): void 831 832Unsubscribes from top session change events. 833 834**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 835 836**System capability**: SystemCapability.Multimedia.AVSession.Manager 837 838**System API**: This is a system API. 839 840**Parameters** 841 842| Name | Type | Mandatory| Description | 843| -------- | -----------------| ---- | ---------------------------- | 844| type | string | Yes | Event type, which is **'topSessionChange'** in this case.| 845| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.<br>The **session** parameter in the callback describes a media session. The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.| 846 847**Error codes** 848 849For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 850 851| ID| Error Message| 852| -------- | ---------------------------------------- | 853| 201 | permission denied. | 854| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 855| 6600101 | Session service exception. | 856 857**Example** 858 859```ts 860avSession.off('topSessionChange'); 861``` 862 863## avSession.on('sessionServiceDie') 864 865on(type: 'sessionServiceDie', callback: () => void): void 866 867Subscribes to session service death events. Upon receiving this event, the application can clear resources. 868 869**System capability**: SystemCapability.Multimedia.AVSession.Core 870 871**System API**: This is a system API. 872 873**Parameters** 874 875| Name | Type | Mandatory| Description | 876| -------- | -------------------- | ---- | ------------------------------------------------------------ | 877| type | string | Yes | Event type. The event **'sessionServiceDie'** is triggered when the session service dies.| 878| callback | callback: () => void | Yes | Callback used for subscription. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object. | 879 880**Error codes** 881 882For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 883 884| ID| Error Message| 885| -------- | ---------------------------------------- | 886| 201 | permission denied. | 887| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 888| 6600101 | Session service exception. | 889 890**Example** 891 892```ts 893avSession.on('sessionServiceDie', () => { 894 console.info('on sessionServiceDie : session is Died '); 895}); 896``` 897 898## avSession.off('sessionServiceDie') 899 900off(type: 'sessionServiceDie', callback?: () => void): void 901 902Unsubscribes from session service death events. 903 904**System capability**: SystemCapability.Multimedia.AVSession.Core 905 906**System API**: This is a system API. 907 908**Parameters** 909 910| Name | Type | Mandatory | Description | 911| ------ | ---------------------- | ---- | ------------------------------------------------------- | 912| type | string | Yes | Event type. The event **'sessionServiceDie'** is triggered when the session service dies.| 913| callback | callback: () => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.<br>The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. | 914 915**Error codes** 916 917For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 918 919| ID| Error Message| 920| -------- | ---------------------------------------- | 921| 201 | permission denied. | 922| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 923| 6600101 | Session service exception. | 924 925**Example** 926 927```ts 928avSession.off('sessionServiceDie'); 929``` 930 931 932## avSession.on('distributedSessionChange')<sup>18+</sup> 933 934on(type: 'distributedSessionChange', distributedSessionType: DistributedSessionType, callback: Callback<Array\<AVSessionController>>): void 935 936Subscribes to the latest distributed remote session change events. 937 938**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES 939 940**System capability**: SystemCapability.Multimedia.AVSession.Manager 941 942**System API**: This is a system API. 943 944**Parameters** 945 946| Name | Type | Mandatory| Description | 947| -------- |-------------------------------------------------------------------------------------| ---- |--------------------------------------------------------------------------| 948| type | string | Yes | Event type. The event **'distributedSessionChange'** is triggered when the latest distributed session is changed.| 949| distributedSessionType | [DistributedSessionType](js-apis-avsession.md#distributedsessiontype18) | Yes | Remote session type. | 950| callback | Callback<Array<[AVSessionController](js-apis-avsession.md#avsessioncontroller10)\>> | Yes | Callback used to return an array of session controller instances of the corresponding type. You can view the session ID, send commands and events to the session, and obtain metadata and playback status information. | 951 952**Error codes** 953 954For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 955 956| ID | Error Message | 957|---------|---------------------------------------------------------------------------------------------------| 958| 202 | Not System App. Interface caller is not a system app. | 959| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 960| 6600101 | Session service exception. | 961 962**Example** 963 964```ts 965avSession.on('distributedSessionChange', avSession.DistributedSessionType.TYPE_SESSION_REMOTE, (sessionControllers: Array<avSession.AVSessionController>) => { 966 console.info(`on distributedSessionChange size: ${sessionControllers.length}`); 967}); 968``` 969 970 971## avSession.off('distributedSessionChange')<sup>18+</sup> 972 973off(type: 'distributedSessionChange', distributedSessionType: DistributedSessionType, callback?: Callback<Array\<AVSessionController>>): void 974 975Unsubscribes from the latest distributed remote session change events. 976 977**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES 978 979**System capability**: SystemCapability.Multimedia.AVSession.Manager 980 981**System API**: This is a system API. 982 983**Parameters** 984 985| Name | Type | Mandatory| Description | 986| -------- |-------------------------------------------------------------------------------------|----|---------------------------------------------------------------| 987| type | string | Yes | Event type. The event **'distributedSessionChange'** is triggered when the latest distributed session is changed. | 988| distributedSessionType | [DistributedSessionType](js-apis-avsession.md#distributedsessiontype18) | Yes | Remote session type. | 989| callback | Callback<Array<[AVSessionController](js-apis-avsession.md#avsessioncontroller10)\>> | No | Callback used for unsubscription. In the callback, the parameter indicates an array of session controller instances of the corresponding type. You can view the session ID, send commands and events to the session, and obtain metadata and playback status information.| 990 991**Error codes** 992 993For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 994 995| ID | Error Message | 996|---------|---------------------------------------------------------------------------------------------------| 997| 202 | Not System App. Interface caller is not a system app. | 998| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 999| 6600101 | Session service exception. | 1000 1001**Example** 1002 1003```ts 1004avSession.off('distributedSessionChange', avSession.DistributedSessionType.TYPE_SESSION_REMOTE); 1005``` 1006 1007## avSession.sendSystemAVKeyEvent 1008 1009sendSystemAVKeyEvent(event: KeyEvent, callback: AsyncCallback\<void>): void 1010 1011Sends a system key event to the top session. This API uses an asynchronous callback to return the result. 1012 1013**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 1014 1015**System capability**: SystemCapability.Multimedia.AVSession.Manager 1016 1017**System API**: This is a system API. 1018 1019**Parameters** 1020 1021| Name | Type | Mandatory| Description | 1022| -------- | ------------------------------------------------------------ | ---- | ------------------------------------- | 1023| event | [KeyEvent](../apis-input-kit/js-apis-keyevent.md#keyevent) | Yes | Key event. | 1024| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the event is sent, **err** is **undefined**; otherwise, **err** is an error object.| 1025 1026**Error codes** 1027 1028For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1029 1030| ID| Error Message| 1031| -------- | ---------------------------------------- | 1032| 201 | permission denied. | 1033| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1034| 6600101 | Session service exception. | 1035| 6600105 | Invalid session command. | 1036 1037**Example** 1038 1039```ts 1040import { KeyEvent } from '@kit.InputKit'; 1041import { BusinessError } from '@kit.BasicServicesKit'; 1042 1043let keyItem: keyEvent.Key = {code:0x49, pressedTime:2, deviceId:0}; 1044let event: keyEvent.KeyEvent = {id:1, deviceId:0, actionTime:1, screenId:1, windowId:1, action:2, key:keyItem, unicodeChar:0, keys:[keyItem], ctrlKey:false, altKey:false, shiftKey:false, logoKey:false, fnKey:false, capsLock:false, numLock:false, scrollLock:false}; 1045 1046avSession.sendSystemAVKeyEvent(event, (err: BusinessError) => { 1047 if (err) { 1048 console.error(`SendSystemAVKeyEvent BusinessError: code: ${err.code}, message: ${err.message}`); 1049 } else { 1050 console.info('SendSystemAVKeyEvent : SUCCESS '); 1051 } 1052}); 1053``` 1054 1055## avSession.sendSystemAVKeyEvent 1056 1057sendSystemAVKeyEvent(event: KeyEvent): Promise\<void> 1058 1059Sends a system key event to the top session. This API uses a promise to return the result. 1060 1061**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 1062 1063**System capability**: SystemCapability.Multimedia.AVSession.Manager 1064 1065**System API**: This is a system API. 1066 1067**Parameters** 1068 1069| Name| Type | Mandatory| Description | 1070| ------ | ------------------------------- | ---- | ---------- | 1071| event | [KeyEvent](../apis-input-kit/js-apis-keyevent.md#keyevent) | Yes | Key event.| 1072 1073**Return value** 1074 1075| Type | Description | 1076| -------------- | ----------------------------- | 1077| Promise\<void> | Promise used to return the result. If the event is sent, no value is returned; otherwise, an error object is returned.| 1078 1079**Error codes** 1080 1081For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1082 1083| ID| Error Message| 1084| -------- | ---------------------------------------- | 1085| 201 | permission denied. | 1086| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1087| 6600101 | Session service exception. | 1088| 6600105 | Invalid session command. | 1089 1090**Example** 1091 1092```ts 1093import { KeyEvent } from '@kit.InputKit'; 1094import { BusinessError } from '@kit.BasicServicesKit'; 1095 1096let keyItem: keyEvent.Key = {code:0x49, pressedTime:2, deviceId:0}; 1097let event: keyEvent.KeyEvent = {id:1, deviceId:0, actionTime:1, screenId:1, windowId:1, action:2, key:keyItem, unicodeChar:0, keys:[keyItem], ctrlKey:false, altKey:false, shiftKey:false, logoKey:false, fnKey:false, capsLock:false, numLock:false, scrollLock:false}; 1098 1099avSession.sendSystemAVKeyEvent(event).then(() => { 1100 console.info('SendSystemAVKeyEvent Successfully'); 1101}).catch((err: BusinessError) => { 1102 console.error(`SendSystemAVKeyEvent BusinessError: code: ${err.code}, message: ${err.message}`); 1103}); 1104``` 1105 1106## avSession.sendSystemControlCommand 1107 1108sendSystemControlCommand(command: AVControlCommand, callback: AsyncCallback\<void>): void 1109 1110Sends a system control command to the top session. This API uses an asynchronous callback to return the result. 1111 1112**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 1113 1114**System capability**: SystemCapability.Multimedia.AVSession.Manager 1115 1116**System API**: This is a system API. 1117 1118**Parameters** 1119 1120| Name | Type | Mandatory| Description | 1121| -------- | ------------------------------------- | ---- | ------------------------------------- | 1122| command | [AVControlCommand](js-apis-avsession.md#avcontrolcommand10) | Yes | Command to send. | 1123| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the command is sent, **err** is **undefined**; otherwise, **err** is an error object.| 1124 1125**Error codes** 1126 1127For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1128 1129| ID| Error Message| 1130| -------- | ---------------------------------------- | 1131| 201 | permission denied. | 1132| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1133| 6600101 | Session service exception. | 1134| 6600105 | Invalid session command. | 1135| 6600107 | Too many commands or events. | 1136 1137**Example** 1138 1139```ts 1140let cmd : avSession.AVControlCommandType = 'play'; 1141// let cmd : avSession.AVControlCommandType = 'pause'; 1142// let cmd : avSession.AVControlCommandType = 'stop'; 1143// let cmd : avSession.AVControlCommandType = 'playNext'; 1144// let cmd : avSession.AVControlCommandType = 'playPrevious'; 1145// let cmd : avSession.AVControlCommandType = 'fastForward'; 1146// let cmd : avSession.AVControlCommandType = 'rewind'; 1147let avcommand: avSession.AVControlCommand = {command:cmd}; 1148// let cmd : avSession.AVControlCommandType = 'seek'; 1149// let avcommand = {command:cmd, parameter:10}; 1150// let cmd : avSession.AVControlCommandType = 'setSpeed'; 1151// let avcommand = {command:cmd, parameter:2.6}; 1152// let cmd : avSession.AVControlCommandType = 'setLoopMode'; 1153// let avcommand = {command:cmd, parameter:avSession.LoopMode.LOOP_MODE_SINGLE}; 1154// let cmd : avSession.AVControlCommandType = 'toggleFavorite'; 1155// let avcommand = {command:cmd, parameter:"false"}; 1156avSession.sendSystemControlCommand(avcommand, (err) => { 1157 if (err) { 1158 console.error(`SendSystemControlCommand BusinessError: code: ${err.code}, message: ${err.message}`); 1159 } else { 1160 console.info('sendSystemControlCommand successfully'); 1161 } 1162}); 1163``` 1164 1165## avSession.sendSystemControlCommand 1166 1167sendSystemControlCommand(command: AVControlCommand): Promise\<void> 1168 1169Sends a system control command to the top session. This API uses a promise to return the result. 1170 1171**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 1172 1173**System capability**: SystemCapability.Multimedia.AVSession.Manager 1174 1175**System API**: This is a system API. 1176 1177**Parameters** 1178 1179| Name | Type | Mandatory| Description | 1180| ------- | ------------------------------------- | ---- | ----------------------------------- | 1181| command | [AVControlCommand](js-apis-avsession.md#avcontrolcommand10) | Yes | Command to send.| 1182 1183**Return value** 1184 1185| Type | Description | 1186| -------------- | ----------------------------- | 1187| Promise\<void> | Promise used to return the result. If the command is sent, no value is returned; otherwise, an error object is returned.| 1188 1189**Error codes** 1190 1191For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1192 1193| ID| Error Message| 1194| -------- | ---------------------------------------- | 1195| 201 | permission denied. | 1196| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1197| 6600101 | Session service exception. | 1198| 6600105 | Invalid session command. | 1199| 6600107 | Too many commands or events. | 1200 1201**Example** 1202 1203```ts 1204import { BusinessError } from '@kit.BasicServicesKit'; 1205 1206let cmd : avSession.AVControlCommandType = 'play'; 1207// let cmd : avSession.AVControlCommandType = 'pause'; 1208// let cmd : avSession.AVControlCommandType = 'stop'; 1209// let cmd : avSession.AVControlCommandType = 'playNext'; 1210// let cmd : avSession.AVControlCommandType = 'playPrevious'; 1211// let cmd : avSession.AVControlCommandType = 'fastForward'; 1212// let cmd : avSession.AVControlCommandType = 'rewind'; 1213let avcommand: avSession.AVControlCommand = {command:cmd}; 1214// let cmd : avSession.AVControlCommandType = 'seek'; 1215// let avcommand = {command:cmd, parameter:10}; 1216// let cmd : avSession.AVControlCommandType = 'setSpeed'; 1217// let avcommand = {command:cmd, parameter:2.6}; 1218// let cmd : avSession.AVControlCommandType = 'setLoopMode'; 1219// let avcommand = {command:cmd, parameter:avSession.LoopMode.LOOP_MODE_SINGLE}; 1220// let cmd : avSession.AVControlCommandType = 'toggleFavorite'; 1221// let avcommand = {command:cmd, parameter:"false"}; 1222avSession.sendSystemControlCommand(avcommand).then(() => { 1223 console.info('SendSystemControlCommand successfully'); 1224}).catch((err: BusinessError) => { 1225 console.error(`SendSystemControlCommand BusinessError: code: ${err.code}, message: ${err.message}`); 1226}); 1227``` 1228 1229## ProtocolType<sup>10+</sup> 1230 1231Enumerates the protocol types supported by the remote device. 1232 1233**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1234 1235| Name | Value | Description | 1236| --------------------------- | ---- | ----------- | 1237| TYPE_CAST_PLUS_MIRROR | 1 | Cast+ mirror mode.<br> **System API**: This is a system API.| 1238 1239## avSession.startCastDeviceDiscovery<sup>10+</sup> 1240 1241startCastDeviceDiscovery(callback: AsyncCallback\<void>): void 1242 1243Starts cast-enabled device discovery. This API uses an asynchronous callback to return the result. 1244 1245**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1246 1247**System API**: This is a system API. 1248 1249**Parameters** 1250 1251| Name | Type | Mandatory| Description | 1252| -------- | ------------------------------------- | ---- | ------------------------------------- | 1253| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the command is sent and device discovery starts, **err** is **undefined**; otherwise, **err** is an error object.| 1254 1255 1256**Example** 1257 1258```ts 1259import { BusinessError } from '@kit.BasicServicesKit'; 1260 1261avSession.startCastDeviceDiscovery((err: BusinessError) => { 1262 if (err) { 1263 console.error(`startCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`); 1264 } else { 1265 console.info('startCastDeviceDiscovery successfully'); 1266 } 1267}); 1268``` 1269 1270## avSession.startCastDeviceDiscovery<sup>10+</sup> 1271 1272startCastDeviceDiscovery(filter: number, callback: AsyncCallback\<void>): void 1273 1274Starts cast-enabled device discovery with filter criteria specified. This API uses an asynchronous callback to return the result. 1275 1276**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1277 1278**System API**: This is a system API. 1279 1280**Parameters** 1281 1282| Name | Type | Mandatory| Description | 1283| -------- | ------------------------------------- | ---- | ------------------------------------- | 1284| filter | number | Yes| Filter criteria for device discovery. The value consists of **ProtocolType**s.| 1285| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the command is sent and device discovery starts, **err** is **undefined**; otherwise, **err** is an error object.| 1286 1287**Error codes** 1288 1289For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1290 1291| ID| Error Message| 1292| -------- | ---------------------------------------- | 1293| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1294 1295**Example** 1296 1297```ts 1298import { BusinessError } from '@kit.BasicServicesKit'; 1299 1300let filter = 2; 1301avSession.startCastDeviceDiscovery(filter, (err: BusinessError) => { 1302 if (err) { 1303 console.error(`startCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`); 1304 } else { 1305 console.info('startCastDeviceDiscovery successfully'); 1306 } 1307}); 1308``` 1309 1310## avSession.startCastDeviceDiscovery<sup>10+</sup> 1311 1312startCastDeviceDiscovery(filter?: number, drmSchemes?: Array\<string>): Promise\<void> 1313 1314Starts cast-enabled device discovery. This API uses a promise to return the result. 1315 1316**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1317 1318**System API**: This is a system API. 1319 1320**Parameters** 1321 1322| Name | Type | Mandatory| Description | 1323| -------- | ------------------------------------- | ---- | ------------------------------------- | 1324| filter | number | No| Filter criteria for device discovery. The value consists of **ProtocolType**s.| 1325| drmSchemes | Array\<string> | No| Filter criteria for discovering devices that support DRM resource playback. The value consists of DRM UUIDs.<br>This parameter is supported since API version 12.| 1326 1327**Return value** 1328 1329| Type | Description | 1330| -------------- | ----------------------------- | 1331| Promise\<void> | Promise used to return the result. If the command is sent and device discovery starts, no value is returned; otherwise, an error object is returned.| 1332 1333**Error codes** 1334 1335For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1336 1337| ID| Error Message| 1338| -------- | ---------------------------------------- | 1339| 202 | Not System App. | 1340| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1341 1342**Example** 1343 1344```ts 1345import { BusinessError } from '@kit.BasicServicesKit'; 1346 1347let filter = 2; 1348let drmSchemes = ['3d5e6d35-9b9a-41e8-b843-dd3c6e72c42c']; 1349avSession.startCastDeviceDiscovery(filter, drmSchemes).then(() => { 1350 console.info('startCastDeviceDiscovery successfully'); 1351}).catch((err: BusinessError) => { 1352 console.error(`startCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`); 1353}); 1354``` 1355 1356## avSession.stopCastDeviceDiscovery<sup>10+</sup> 1357 1358stopCastDeviceDiscovery(callback: AsyncCallback\<void>): void 1359 1360Stops cast-enabled device discovery. This API uses an asynchronous callback to return the result. 1361 1362**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1363 1364**System API**: This is a system API. 1365 1366**Parameters** 1367 1368| Name | Type | Mandatory| Description | 1369| -------- | ------------------------------------- | ---- | ------------------------------------- | 1370| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If device discovery stops, **err** is **undefined**; otherwise, **err** is an error object.| 1371 1372 1373**Example** 1374 1375```ts 1376import { BusinessError } from '@kit.BasicServicesKit'; 1377 1378avSession.stopCastDeviceDiscovery((err: BusinessError) => { 1379 if (err) { 1380 console.error(`stopCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`); 1381 } else { 1382 console.info('stopCastDeviceDiscovery successfully'); 1383 } 1384}); 1385``` 1386 1387## avSession.stopCastDeviceDiscovery<sup>10+</sup> 1388 1389stopCastDeviceDiscovery(): Promise\<void> 1390 1391Stops cast-enabled device discovery. This API uses a promise to return the result. 1392 1393**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1394 1395**System API**: This is a system API. 1396 1397**Return value** 1398 1399| Type | Description | 1400| -------------- | ----------------------------- | 1401| Promise\<void> | Promise used to return the result. If device discovery stops, no value is returned; otherwise, an error object is returned.| 1402 1403**Example** 1404 1405```ts 1406import { BusinessError } from '@kit.BasicServicesKit'; 1407 1408avSession.stopCastDeviceDiscovery().then(() => { 1409 console.info('stopCastDeviceDiscovery successfully'); 1410}).catch((err: BusinessError) => { 1411 console.error(`stopCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`); 1412}); 1413``` 1414 1415## avSession.setDiscoverable<sup>10+</sup> 1416 1417setDiscoverable(enable: boolean, callback: AsyncCallback\<void>): void 1418 1419Sets whether to allow the device discoverable. A discoverable device can be used as the cast receiver. This API uses an asynchronous callback to return the result. 1420 1421**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1422 1423**System API**: This is a system API. 1424 1425**Parameters** 1426 1427| Name | Type | Mandatory| Description | 1428| -------- | ------------------------------------- | ---- | ------------------------------------- | 1429| enable | boolean | Yes| Whether to allow the device discoverable. The value **true** means to allow the device discoverable, and **false** means the opposite.| 1430| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the setting is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1431 1432**Error codes** 1433 1434For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1435 1436| ID| Error Message| 1437| -------- | ---------------------------------------- | 1438| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1439 1440**Example** 1441 1442```ts 1443import { BusinessError } from '@kit.BasicServicesKit'; 1444 1445avSession.setDiscoverable(true, (err: BusinessError) => { 1446 if (err) { 1447 console.error(`setDiscoverable BusinessError: code: ${err.code}, message: ${err.message}`); 1448 } else { 1449 console.info('setDiscoverable successfully'); 1450 } 1451}); 1452``` 1453 1454## avSession.setDiscoverable<sup>10+</sup> 1455 1456setDiscoverable(enable: boolean): Promise\<void> 1457 1458Sets whether to allow the device discoverable. A discoverable device can be used as the cast receiver. This API uses a promise to return the result. 1459 1460**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1461 1462**System API**: This is a system API. 1463 1464**Parameters** 1465 1466| Name | Type | Mandatory| Description | 1467| -------- | ------------------------------------- | ---- | ------------------------------------- | 1468| enable | boolean | Yes| Whether to allow the device discoverable. The value **true** means to allow the device discoverable, and **false** means the opposite.| 1469 1470**Error codes** 1471 1472For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1473 1474| ID| Error Message| 1475| -------- | ---------------------------------------- | 1476| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1477 1478**Return value** 1479 1480| Type | Description | 1481| -------------- | ----------------------------- | 1482| Promise\<void> | Promise used to return the result. If the setting is successful, no value is returned; otherwise, an error object is returned.| 1483 1484**Example** 1485 1486```ts 1487import { BusinessError } from '@kit.BasicServicesKit'; 1488 1489avSession.setDiscoverable(true).then(() => { 1490 console.info('setDiscoverable successfully'); 1491}).catch((err: BusinessError) => { 1492 console.error(`setDiscoverable BusinessError: code: ${err.code}, message: ${err.message}`); 1493}); 1494``` 1495 1496## avSession.on('deviceAvailable')<sup>10+</sup> 1497 1498on(type: 'deviceAvailable', callback: (device: OutputDeviceInfo) => void): void 1499 1500Subscribes to device discovery events. 1501 1502**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1503 1504**System API**: This is a system API. 1505 1506**Parameters** 1507 1508| Name | Type | Mandatory| Description | 1509| -------- | -------------------- | ---- | ------------------------------------------------------------ | 1510| type | string | Yes | Event type. The event **'deviceAvailable'** is triggered when a device is discovered.| 1511| callback | (device: [OutputDeviceInfo](js-apis-avsession.md#outputdeviceinfo10)) => void | Yes | Callback used for subscription. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object. | 1512 1513**Error codes** 1514 1515For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1516 1517| ID| Error Message| 1518| -------- | ---------------------------------------- | 1519| 201 | permission denied. | 1520| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1521 1522**Example** 1523 1524```ts 1525let castDevice: avSession.OutputDeviceInfo; 1526avSession.on('deviceAvailable', (device: avSession.OutputDeviceInfo) => { 1527 castDevice = device; 1528 console.info(`on deviceAvailable : ${device} `); 1529}); 1530``` 1531 1532## avSession.off('deviceAvailable')<sup>10+</sup> 1533 1534off(type: 'deviceAvailable', callback?: (device: OutputDeviceInfo) => void): void 1535 1536Unsubscribes from device discovery events. 1537 1538**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1539 1540**System API**: This is a system API. 1541 1542**Parameters** 1543 1544| Name | Type | Mandatory | Description | 1545| ------ | ---------------------- | ---- | ------------------------------------------------------- | 1546| type | string | Yes | Event type. The event **'deviceAvailable'** is triggered when a device is discovered.| 1547| callback | (device: [OutputDeviceInfo](js-apis-avsession.md#outputdeviceinfo10)) => void | No | Callback used to return the device information.| 1548 1549**Error codes** 1550 1551For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1552 1553| ID| Error Message| 1554| -------- | ---------------------------------------- | 1555| 201 | permission denied. | 1556| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1557 1558**Example** 1559 1560```ts 1561avSession.off('deviceAvailable'); 1562``` 1563 1564## avSession.on('deviceOffline')<sup>11+</sup> 1565 1566on(type: 'deviceOffline', callback: (deviceId: string) => void): void 1567 1568Subscribes to device offline events. 1569 1570**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1571 1572**System API**: This is a system API. 1573 1574**Parameters** 1575 1576| Name | Type | Mandatory| Description | 1577| -------- | -------------------- | ---- | ------------------------------------------------------------ | 1578| type | string | Yes | Event type. The event **'deviceOffline'** is triggered when a device gets offline.| 1579| callback | (deviceId: string) => void | Yes | Callback used to return the result. The **deviceId** parameter in the callback indicates the device ID. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object. | 1580 1581**Error codes** 1582 1583For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1584 1585| ID| Error Message| 1586| -------- | ---------------------------------------- | 1587| 201 | permission denied. | 1588| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1589 1590**Example** 1591 1592```ts 1593let castDeviceId: string; 1594avSession.on('deviceOffline', (deviceId: string) => { 1595 castDeviceId = deviceId; 1596 console.info(`on deviceOffline : ${deviceId} `); 1597}); 1598``` 1599 1600## avSession.off('deviceOffline')<sup>11+</sup> 1601 1602off(type: 'deviceOffline', callback?: (deviceId: string) => void): void 1603 1604Unsubscribes from device offline events. 1605 1606**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES 1607 1608**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1609 1610**System API**: This is a system API. 1611 1612**Parameters** 1613 1614| Name | Type | Mandatory | Description | 1615| ------ | ---------------------- | ---- | ------------------------------------------------------- | 1616| type | string | Yes | Event type, which is **'deviceOffline'** in this case.| 1617| callback | (deviceId: string) => void | No | Callback used to return the result. The **deviceId** parameter in the callback indicates the device ID. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object. The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.| 1618 1619**Error codes** 1620 1621For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1622 1623| ID| Error Message| 1624| -------- | ---------------------------------------- | 1625| 201 | permission denied. | 1626| 202 | Not System App. | 1627| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 1628 1629**Example** 1630 1631```ts 1632avSession.off('deviceOffline'); 1633``` 1634 1635## avSession.getAVCastController<sup>10+</sup> 1636 1637getAVCastController(sessionId: string, callback: AsyncCallback\<AVCastController>): void 1638 1639Obtains the cast controller when a casting connection is set up. This API uses an asynchronous callback to return the result. 1640 1641This API can be called on both the local and remote devices. You can use the API to obtain the same controller to control audio playback after cast. 1642 1643**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1644 1645**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES 1646 1647**System API**: This is a system API. 1648 1649**Parameters** 1650 1651| Name | Type | Mandatory| Description | 1652| --------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | 1653| sessionId | string | Yes |Session ID.| 1654| callback | AsyncCallback<[AVCastController](#avcastcontroller10)\> | Yes | Callback used to return the cast controller.| 1655 1656**Error codes** 1657 1658For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1659 1660| ID| Error Message| 1661| -------- | ---------------------------------------- | 1662| 201 | permission denied. | 1663| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1664| 6600101 | Session service exception | 1665| 6600102 | session does not exist | 1666 1667**Example** 1668 1669```ts 1670import { BusinessError } from '@kit.BasicServicesKit'; 1671 1672let currentAVSession: avSession.AVSession | undefined = undefined; 1673let tag = "createNewSession"; 1674let context: Context = getContext(this); 1675let sessionId: string = ""; // Used as an input parameter of subsequent functions. 1676 1677let aVCastController: avSession.AVCastController; 1678avSession.getAVCastController(sessionId , (err: BusinessError, avcontroller: avSession.AVCastController) => { 1679 if (err) { 1680 console.error(`getAVCastController BusinessError: code: ${err.code}, message: ${err.message}`); 1681 } else { 1682 aVCastController = avcontroller; 1683 console.info('getAVCastController : SUCCESS '); 1684 } 1685}); 1686``` 1687 1688## avSession.getAVCastController<sup>10+</sup> 1689 1690getAVCastController(sessionId: string): Promise\<AVCastController> 1691 1692Obtains the cast controller when a casting connection is set up. This API uses a promise to return the result. 1693 1694This API can be called on both the local and remote devices. You can use the API to obtain the same controller to control audio playback after cast. 1695 1696**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1697 1698**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES 1699 1700**System API**: This is a system API. 1701 1702**Parameters** 1703 1704| Name | Type | Mandatory| Description | 1705| --------- | ------------------------- | ---- | ------------------------------------------------------------ | 1706| sessionId | string | Yes |Session ID.| 1707 1708**Return value** 1709 1710| Type | Description | 1711| --------- | ------------------------------------------------------------ | 1712| Promise<[AVCastController](#avcastcontroller10)\> | Promise used to return the cast controller.| 1713 1714**Error codes** 1715 1716For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1717 1718| ID| Error Message| 1719| -------- | ---------------------------------------- | 1720| 201 | permission denied. | 1721| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 1722| 6600101 | server exception | 1723| 6600102 | The session does not exist | 1724 1725**Example** 1726 1727```ts 1728import { BusinessError } from '@kit.BasicServicesKit'; 1729 1730let currentAVSession: avSession.AVSession | undefined = undefined; 1731let tag = "createNewSession"; 1732let context: Context = getContext(this); 1733let sessionId: string = ""; // Used as an input parameter of subsequent functions. 1734 1735let aVCastController: avSession.AVCastController; 1736avSession.getAVCastController(sessionId).then((avcontroller: avSession.AVCastController) => { 1737 aVCastController = avcontroller; 1738 console.info('getAVCastController : SUCCESS'); 1739}).catch((err: BusinessError) => { 1740 console.error(`getAVCastController BusinessError: code: ${err.code}, message: ${err.message}`); 1741}); 1742``` 1743 1744## avSession.startCasting<sup>10+</sup> 1745 1746startCasting(session: SessionToken, device: OutputDeviceInfo, callback: AsyncCallback\<void>): void 1747 1748Starts casting. This API uses an asynchronous callback to return the result. 1749 1750**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 1751 1752**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1753 1754**System API**: This is a system API. 1755 1756**Parameters** 1757 1758| Name | Type | Mandatory| Description | 1759| -------- | ------------------------------------- | ---- | ------------------------------------- | 1760| session | [SessionToken](#sessiontoken) | Yes | Session token. | 1761| device | [OutputDeviceInfo](js-apis-avsession.md#outputdeviceinfo10) | Yes | Device-related information.| 1762| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the command is sent and casting starts, **err** is **undefined**; otherwise, **err** is an error object.| 1763 1764**Error codes** 1765 1766For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1767 1768| ID| Error Message| 1769| -------- | ---------------------------------------- | 1770| 201 | permission denied. | 1771| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1772| 6600101 | Session service exception. | 1773| 6600108 | Device connection failed. | 1774 1775**Example** 1776 1777```ts 1778import { BusinessError } from '@kit.BasicServicesKit'; 1779 1780let myToken: avSession.SessionToken = { 1781 sessionId: sessionId, 1782} 1783let castDevice: avSession.OutputDeviceInfo | undefined = undefined; 1784avSession.on('deviceAvailable', (device: avSession.OutputDeviceInfo) => { 1785 castDevice = device; 1786 console.info(`on deviceAvailable : ${device} `); 1787}); 1788if (castDevice !== undefined) { 1789 avSession.startCasting(myToken, castDevice, (err: BusinessError) => { 1790 if (err) { 1791 console.error(`startCasting BusinessError: code: ${err.code}, message: ${err.message}`); 1792 } else { 1793 console.info('startCasting successfully'); 1794 } 1795 }); 1796} 1797``` 1798 1799 1800## avSession.startCasting<sup>10+</sup> 1801 1802startCasting(session: SessionToken, device: OutputDeviceInfo): Promise\<void> 1803 1804Starts casting. This API uses a promise to return the result. 1805 1806**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications) 1807 1808**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1809 1810**System API**: This is a system API. 1811 1812**Parameters** 1813 1814| Name | Type | Mandatory| Description | 1815| -------- | ------------------------------------- | ---- | ------------------------------------- | 1816| session | [SessionToken](#sessiontoken) | Yes | Session token. | 1817| device | [OutputDeviceInfo](js-apis-avsession.md#outputdeviceinfo10) | Yes | Device-related information.| 1818 1819**Return value** 1820 1821| Type | Description | 1822| -------------- | ----------------------------- | 1823| Promise\<void> | Promise used to return the result. If the command is sent and casting starts, no value is returned; otherwise, an error object is returned.| 1824 1825**Error codes** 1826 1827For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1828 1829| ID| Error Message| 1830| -------- | ---------------------------------------- | 1831| 201 | permission denied. | 1832| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1833| 6600101 | Session service exception. | 1834| 6600108 | Device connection failed. | 1835 1836**Example** 1837 1838```ts 1839import { BusinessError } from '@kit.BasicServicesKit'; 1840 1841let myToken: avSession.SessionToken = { 1842 sessionId: sessionId, 1843} 1844let castDevice: avSession.OutputDeviceInfo | undefined = undefined; 1845avSession.on('deviceAvailable', (device: avSession.OutputDeviceInfo) => { 1846 castDevice = device; 1847 console.info(`on deviceAvailable : ${device} `); 1848}); 1849if (castDevice !== undefined) { 1850 avSession.startCasting(myToken, castDevice).then(() => { 1851 console.info('startCasting successfully'); 1852 }).catch((err: BusinessError) => { 1853 console.error(`startCasting BusinessError: code: ${err.code}, message: ${err.message}`); 1854 }); 1855} 1856``` 1857 1858## avSession.stopCasting<sup>10+</sup> 1859 1860stopCasting(session: SessionToken, callback: AsyncCallback\<void>): void 1861 1862Stops castings. This API uses an asynchronous callback to return the result. 1863 1864**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1865 1866**System API**: This is a system API. 1867 1868**Parameters** 1869 1870| Name | Type | Mandatory| Description | 1871| -------- | ------------------------------------- | ---- | ------------------------------------- | 1872| session | [SessionToken](#sessiontoken) | Yes | Session token. | 1873| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If casting stops, **err** is **undefined**; otherwise, **err** is an error object.| 1874 1875**Error codes** 1876 1877For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1878 1879| ID| Error Message| 1880| -------- | ---------------------------------------- | 1881| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1882| 6600109 | The remote connection is not established. | 1883 1884**Example** 1885 1886```ts 1887import { BusinessError } from '@kit.BasicServicesKit'; 1888 1889let myToken: avSession.SessionToken = { 1890 sessionId: sessionId, 1891} 1892avSession.stopCasting(myToken, (err: BusinessError) => { 1893 if (err) { 1894 console.error(`stopCasting BusinessError: code: ${err.code}, message: ${err.message}`); 1895 } else { 1896 console.info('stopCasting successfully'); 1897 } 1898}); 1899``` 1900 1901## avSession.stopCasting<sup>10+</sup> 1902 1903stopCasting(session: SessionToken): Promise\<void> 1904 1905Stops castings. This API uses a promise to return the result. 1906 1907**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1908 1909**System API**: This is a system API. 1910 1911**Parameters** 1912 1913| Name | Type | Mandatory| Description | 1914| -------- | ------------------------------------- | ---- | ------------------------------------- | 1915| session | [SessionToken](#sessiontoken) | Yes | Session token. | 1916 1917**Return value** 1918 1919| Type | Description | 1920| -------------- | ----------------------------- | 1921| Promise\<void> | Promise used to return the result. If casting stops, no value is returned; otherwise, an error object is returned.| 1922 1923**Error codes** 1924 1925For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1926 1927| ID| Error Message| 1928| -------- | ---------------------------------------- | 1929| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. | 1930| 6600109 | The remote connection is not established. | 1931 1932**Example** 1933 1934```ts 1935import { BusinessError } from '@kit.BasicServicesKit'; 1936 1937let myToken: avSession.SessionToken = { 1938 sessionId: sessionId, 1939} 1940avSession.stopCasting(myToken).then(() => { 1941 console.info('stopCasting successfully'); 1942}).catch((err: BusinessError) => { 1943 console.error(`stopCasting BusinessError: code: ${err.code}, message: ${err.message}`); 1944}); 1945``` 1946 1947## avSession.startDeviceLogging<sup>13+</sup> 1948 1949startDeviceLogging(url: string, maxSize?: number): Promise\<void> 1950 1951Starts to write device logs to a file. This API uses a promise to return the result. 1952 1953**System capability**: SystemCapability.Multimedia.AVSession.AVCast 1954 1955**System API**: This is a system API. 1956 1957**Parameters** 1958 1959| Name | Type | Mandatory| Description | 1960| -------- | ------------------------------------- | ---- | ------------------------------------- | 1961| url | string | Yes | Target file descriptor (unique identifier used to open a file).| 1962| maxSize | number | No | Maximum size of the log file, in KB.| 1963 1964**Return value** 1965 1966| Type | Description | 1967| -------------- | ----------------------------- | 1968| Promise\<void> | Promise used to return the result. If the device logs are written to the file successfully, no result is returned; otherwise, an error object is returned.| 1969 1970**Error codes** 1971 1972For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 1973 1974| ID| Error Message| 1975| -------- | ---------------------------------------- | 1976| 202 | Not System App. | 1977| 401 | Parameter check failed. 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.| 1978| 6600101 | Session service exception. | 1979| 6600102 | The session does not exist. | 1980 1981**Example** 1982 1983```ts 1984import { BusinessError } from '@kit.BasicServicesKit'; 1985import { fileIo } from '@kit.CoreFileKit'; 1986 1987let file = await fileIo.open("filePath"); 1988let url = file.fd.toString(); 1989avSession.startDeviceLogging(url, 2048).then(() => { 1990 console.info('startDeviceLogging successfully'); 1991}).catch((err: BusinessError) => { 1992 console.error(`startDeviceLogging BusinessError: code: ${err.code}, message: ${err.message}`); 1993}) 1994``` 1995 1996## avSession.stopDeviceLogging<sup>13+</sup> 1997 1998stopDeviceLogging(): Promise\<void> 1999 2000Stops device logging. This API uses a promise to return the result. 2001 2002**System capability**: SystemCapability.Multimedia.AVSession.AVCast 2003 2004**System API**: This is a system API. 2005 2006**Return value** 2007 2008| Type | Description | 2009| -------------- | ----------------------------- | 2010| Promise\<void> | Promise used to return the result. If device logging is stopped, no result is returned; otherwise, an error object is returned.| 2011 2012**Error codes** 2013 2014For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 2015 2016| ID| Error Message| 2017| -------- | ---------------------------------------- | 2018| 202 | Not System App. | 2019| 6600101 | Session service exception. | 2020| 6600102 | The session does not exist. | 2021 2022**Example** 2023 2024```ts 2025import { BusinessError } from '@kit.BasicServicesKit'; 2026 2027avSession.stopDeviceLogging().then(() => { 2028 console.info('stopCasting successfully'); 2029}).catch((err: BusinessError) => { 2030 console.error(`stopCasting BusinessError: code: ${err.code}, message: ${err.message}`); 2031}); 2032``` 2033 2034## avSession.on('deviceLogEvent')<sup>13+</sup> 2035 2036on(type: 'deviceLogEvent', callback: Callback\<DeviceLogEventCode>): void 2037 2038Subscribes to device log events. 2039 2040**System capability**: SystemCapability.Multimedia.AVSession.AVCast 2041 2042**System API**: This is a system API. 2043 2044**Parameters** 2045 2046| Name | Type | Mandatory| Description | 2047| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2048| type | string | Yes | Event type, which is **'deviceLogEvent'** in this case.| 2049| callback | (callback: [DeviceLogEventCode](#devicelogeventcode13)) => void | Yes | Callback function, in which **DeviceLogEventCode** is the return value of the current device log event. | 2050 2051**Error codes** 2052 2053For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 2054 2055| ID| Error Message| 2056| -------- | ---------------------------------------- | 2057| 202 | Not System App. | 2058| 401 | Parameter check failed. 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.| 2059| 6600101 | Session service exception. | 2060| 6600102 | The session does not exist. | 2061 2062**Example** 2063 2064```ts 2065avSession.on('deviceLogEvent', (eventCode: avSession.DeviceLogEventCode) => { 2066 console.info(`on deviceLogEvent code : ${eventCode}`); 2067}); 2068``` 2069 2070## avSession.off('deviceLogEvent')<sup>13+</sup> 2071 2072off(type: 'deviceLogEvent', callback?: Callback\<DeviceLogEventCode>): void 2073 2074Unsubscribes from device log events. 2075 2076**System capability**: SystemCapability.Multimedia.AVSession.AVCast 2077 2078**System API**: This is a system API. 2079 2080**Parameters** 2081 2082| Name | Type | Mandatory| Description | 2083| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 2084| type | string | Yes | Event type, which is **'deviceLogEvent'** in this case.| 2085| callback | (callback: [DeviceLogEventCode](#devicelogeventcode13)) => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object. The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. | 2086 2087**Error codes** 2088 2089For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 2090 2091| ID| Error Message| 2092| -------- | ---------------------------------------- | 2093| 202 | Not System App. | 2094| 401 | Parameter check failed. 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types.| 2095| 6600101 | Session service exception. | 2096| 6600102 | The session does not exist. | 2097 2098**Example** 2099 2100```ts 2101avSession.off('deviceLogEvent'); 2102``` 2103 2104## AVCastController<sup>10+</sup> 2105 2106After a casting connection is set up, you can call [avSession.getAVCastController](js-apis-avsession.md#getavcastcontroller10) to obtain the cast controller. Through the controller, you can query the session ID, send commands and events to a session, and obtain session metadata and playback state information. 2107 2108### setDisplaySurface<sup>10+</sup> 2109 2110setDisplaySurface(surfaceId: string): Promise\<void> 2111 2112Sets the surface ID for playback, which is used at the cast receiver (sink). This API uses a promise to return the result. 2113 2114**System capability**: SystemCapability.Multimedia.AVSession.AVCast 2115 2116**System API**: This is a system API. 2117 2118**Return value** 2119 2120| Type | Description | 2121| --------------------------------------------- | --------------------------- | 2122| Promise\<void> | Promise used to return the result.| 2123 2124**Error codes** 2125 2126For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 2127 2128| ID| Error Message| 2129| -------- | ---------------------------------------- | 2130| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 2131| 6600109 | The remote connection is not established. | 2132 2133**Example** 2134 2135```ts 2136import { media } from '@kit.MediaKit'; 2137let surfaceID: string = ''; 2138media.createAVRecorder().then((avRecorder) => { 2139 avRecorder.getInputSurface((err: BusinessError, surfaceId: string) => { 2140 if (err == null) { 2141 console.info('getInputSurface success'); 2142 surfaceID = surfaceId; 2143 } else { 2144 console.error('getInputSurface failed and error is ' + err.message); 2145 } 2146 }); 2147}) 2148aVCastController.setDisplaySurface(surfaceID).then(() => { 2149 console.info('setDisplaySurface : SUCCESS'); 2150}); 2151``` 2152 2153### setDisplaySurface<sup>10+</sup> 2154 2155setDisplaySurface(surfaceId: string, callback: AsyncCallback\<void>): void 2156 2157Sets the surface ID for playback, which is used at the cast receiver (sink). This API uses an asynchronous callback to return the result. 2158 2159**System capability**: SystemCapability.Multimedia.AVSession.AVCast 2160 2161**System API**: This is a system API. 2162 2163**Parameters** 2164 2165| Name | Type | Mandatory| Description | 2166| -------- | --------------------------------------------------- | ---- | ---------------------------- | 2167| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 2168| surfaceId | string | Yes | Surface ID.| 2169 2170 2171**Error codes** 2172 2173For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 2174 2175| ID| Error Message| 2176| -------- | ---------------------------------------- | 2177| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. | 2178| 6600109 | The remote connection is not established. | 2179 2180**Example** 2181 2182```ts 2183import { BusinessError } from '@kit.BasicServicesKit'; 2184import { media } from '@kit.MediaKit'; 2185let surfaceID: string = ''; 2186media.createAVRecorder().then((avRecorder) => { 2187 avRecorder.getInputSurface((err: BusinessError, surfaceId: string) => { 2188 if (err == null) { 2189 console.info('getInputSurface success'); 2190 surfaceID = surfaceId; 2191 } else { 2192 console.error('getInputSurface failed and error is ' + err.message); 2193 } 2194 }); 2195}) 2196aVCastController.setDisplaySurface(surfaceID, (err: BusinessError) => { 2197 if (err) { 2198 console.error(`setDisplaySurface BusinessError: code: ${err.code}, message: ${err.message}`); 2199 } else { 2200 console.info('setDisplaySurface : SUCCESS'); 2201 } 2202}); 2203``` 2204 2205### on('videoSizeChange')<sup>12+</sup> 2206 2207on(type: 'videoSizeChange', callback: (width:number, height:number) => void): void 2208 2209Subscribes to video size change events. 2210 2211**System capability**: SystemCapability.Multimedia.AVSession.AVCast 2212 2213**System API**: This is a system API. 2214 2215**Parameters** 2216 2217| Name | Type | Mandatory| Description | 2218| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- | 2219| type | string | Yes | Event type. The event **'videoSizeChange'** is triggered when the video size changes.| 2220| callback | (width:number, height:number) => void | Yes | Callback used to return the video width and height. | 2221 2222**Error codes** 2223 2224For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 2225 2226| ID| Error Message| 2227| -------- | ---------------- | 2228| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 2229| 6600101 | Session service exception. | 2230 2231**Example** 2232 2233```ts 2234aVCastController.on('videoSizeChange', (width: number, height: number) => { 2235 console.info(`width : ${width} `); 2236 console.info(`height: ${height} `); 2237}); 2238``` 2239 2240### off('videoSizeChange')<sup>12+</sup> 2241 2242off(type: 'videoSizeChange'): void 2243 2244Unsubscribes from video size changes. 2245 2246**System capability**: SystemCapability.Multimedia.AVSession.AVCast 2247 2248**System API**: This is a system API. 2249 2250**Parameters** 2251 2252| Name | Type | Mandatory| Description | 2253| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- | 2254| type | string | Yes | Event type, which is **'videoSizeChange'** in this case. | 2255 2256**Error codes** 2257 2258For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md). 2259 2260| ID| Error Message| 2261| -------- | ---------------- | 2262| 401 | parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. | 2263| 6600101 | Session service exception. | 2264 2265**Example** 2266 2267```ts 2268aVCastController.off('videoSizeChange'); 2269``` 2270 2271## AVMetadata<sup>10+</sup> 2272 2273Describes the media metadata. 2274 2275**System capability**: SystemCapability.Multimedia.AVSession.Core 2276 2277| Name | Type | Mandatory| Description | 2278| --------------- |-------------------------| ---- |---------------------------------------------------------------------| 2279| avQueueName<sup>12+</sup> | string | No | Playlist name.<br>This is a system API.| 2280 2281## AVQueueInfo<sup>11+</sup> 2282 2283Defines the attributes of a playlist. 2284 2285**System capability**: SystemCapability.Multimedia.AVSession.Core 2286 2287**System API**: This is a system API. 2288 2289| Name | Type | Mandatory| Description | 2290| --------------- |-------------------------| ---- |--------------------------------------------------------------------- | 2291| bundleName | string | Yes | Bundle name of the application to which the playlist belongs. | 2292| avQueueName | string | Yes | Playlist name. | 2293| avQueueId | string | Yes | Unique ID of the playlist. | 2294| avQueueImage | image.PixelMap | string |Yes | Cover image of the playlist, which can be pixel data of an image or an image path (local path or Internet path). | 2295| lastPlayedTime | number | No | Last time when the playlist is played. | 2296 2297## DeviceInfo<sup>10+</sup> 2298 2299Describes the information related to the output device. 2300 2301| Name | Type | Mandatory| Description | 2302| ---------- | -------------- | ---- | ---------------------- | 2303| ipAddress | string | No | IP address of the output device.<br>This is a system API.<br> **System capability**: SystemCapability.Multimedia.AVSession.AVCast | 2304| providerId | number | No | Vendor of the output device.<br>This is a system API.<br> **System capability**: SystemCapability.Multimedia.AVSession.AVCast | 2305| authenticationStatus<sup>11+</sup> | number | No | Whether the output device is trusted. The default value is **0**, indicating that the device is untrusted. The value **1** means that the device is trusted.<br>This is a system API.<br> **System capability**: SystemCapability.Multimedia.AVSession.AVCast | 2306| networkId<sup>13+</sup> | string | No | Network ID of the output device.<br>This is a system API.<br> **System capability**: SystemCapability.Multimedia.AVSession.AVCast| 2307 2308## AVSessionDescriptor 2309 2310Declares the session descriptor. 2311 2312**System capability**: SystemCapability.Multimedia.AVSession.Manager 2313 2314**System API**: This is a system API. 2315 2316| Name | Type | Readable| Writable| Description | 2317| --------------| ---------------- | ---------------- | ---------------- |------| 2318| sessionId | string | Yes| Yes | Session ID. | 2319| type | [AVSessionType](js-apis-avsession.md#avsessiontype10) | Yes| Yes| Session type. | 2320| sessionTag | string | Yes| Yes| Custom session name. | 2321| elementName | [ElementName](../apis-ability-kit/js-apis-bundle-ElementName.md) | Yes| Yes| Information about the application to which the session belongs, including the bundle name and ability name.| 2322| isActive | boolean | Yes| Yes| Whether the session is activated.<br>**true**: The session is activated.<br>**false**: The service is not activated. | 2323| isTopSession | boolean | Yes| Yes| Whether the session is the top session.<br>**true**: The session is the top session.<br>**false**: The session is not the top session. | 2324| outputDevice | [OutputDeviceInfo](js-apis-avsession.md#outputdeviceinfo10) | Yes| Yes| Information about the output device. | 2325 2326## DeviceLogEventCode<sup>13+</sup> 2327 2328Enumerates the return values of device log events. 2329 2330**System capability**: SystemCapability.Multimedia.AVSession.AVCast 2331 2332**System API**: This is a system API. 2333 2334| Name | Value | Description | 2335| --------------------------- | ---- | ----------- | 2336| DEVICE_LOG_FULL | 1 | The log file is full. | 2337| DEVICE_LOG_EXCEPTION | 2 | An exception occurs during device logging.| 2338