• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Interface (AVSessionController)
2<!--Kit: AVSession Kit-->
3<!--Subsystem: Multimedia-->
4<!--Owner: @ccfriend; @liao_qian-->
5<!--SE: @ccfriend-->
6<!--TSE: @chenmingxi1_huawei-->
7
8> **NOTE**
9>
10> - 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.
11> - The initial APIs of this interface are supported since API version 10.
12
13Through the AV session controller, you can query the session ID, send commands and events to a session, and obtain session metadata and playback state information.
14
15## Modules to Import
16
17```ts
18import { avSession } from '@kit.AVSessionKit';
19```
20
21## Properties
22
23**Atomic service API**: This API can be used in atomic services since API version 12.
24
25**System capability**: SystemCapability.Multimedia.AVSession.Core
26
27| Name     | Type  | Read-Only| Optional| Description                                   |
28| :-------- | :----- | :--- | :--- | :-------------------------------------- |
29| sessionId<sup>10+</sup> | string | Yes  | No  | Unique session ID of the AVSessionController object.|
30
31
32**Example**
33
34```ts
35import { BusinessError } from '@kit.BasicServicesKit';
36import { avSession } from '@kit.AVSessionKit';
37
38let tag: string = "createNewSession";
39let sessionId: string = "";
40let AVSessionController: avSession.AVSessionController;
41avSession.createAVSession(context, tag, "audio").then(async (data:avSession.AVSession)=> {
42  currentAVSession = data;
43  sessionId = currentAVSession.sessionId;
44  AVSessionController = await currentAVSession.getController();
45  console.info('CreateAVSession : SUCCESS :sessionid = ${sessionid}');
46}).catch((err: BusinessError) => {
47  console.error(`CreateController BusinessError: code: ${err.code}, message: ${err.message}`);
48});
49```
50
51## getAVPlaybackState<sup>10+</sup>
52
53getAVPlaybackState(callback: AsyncCallback\<AVPlaybackState>): void
54
55Obtains the remote playback state. This API uses an asynchronous callback to return the result.
56
57**System capability**: SystemCapability.Multimedia.AVSession.Core
58
59**Parameters**
60
61| Name   | Type                                                       | Mandatory| Description                                                        |
62| --------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ |
63| callback  | AsyncCallback<[AVPlaybackState](arkts-apis-avsession-i.md#avplaybackstate10)\> | Yes  | Callback used to return the remote playback state.|
64
65**Error codes**
66
67For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
68
69| ID| Error Message|
70| -------- | ---------------------------------------- |
71| 6600101  | Session service exception. |
72| 6600102  | The session does not exist. |
73| 6600103  | The session controller does not exist. |
74
75**Example**
76
77```ts
78import { BusinessError } from '@kit.BasicServicesKit';
79
80avsessionController.getAVPlaybackState((err: BusinessError, state: avSession.AVPlaybackState) => {
81  if (err) {
82    console.error(`getAVPlaybackState BusinessError: code: ${err.code}, message: ${err.message}`);
83  } else {
84    console.info('getAVPlaybackState : SUCCESS');
85  }
86});
87```
88
89## getAVPlaybackState<sup>10+</sup>
90
91getAVPlaybackState(): Promise\<AVPlaybackState>
92
93Obtains the remote playback state. This API uses a promise to return the result.
94
95**Atomic service API**: This API can be used in atomic services since API version 12.
96
97**System capability**: SystemCapability.Multimedia.AVSession.Core
98
99**Return value**
100
101| Type                                                       | Description                                                        |
102| --------- | ------------------------------------------------------------ |
103| Promise<[AVPlaybackState](arkts-apis-avsession-i.md#avplaybackstate10)\>  | Promise used to return the remote playback state. |
104
105**Error codes**
106
107For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
108
109| ID| Error Message|
110| -------- | ---------------------------------------- |
111| 6600101  | Session service exception. |
112| 6600102  | The session does not exist. |
113| 6600103  | The session controller does not exist. |
114
115**Example**
116
117```ts
118import { BusinessError } from '@kit.BasicServicesKit';
119
120avsessionController.getAVPlaybackState().then((state: avSession.AVPlaybackState) => {
121  console.info('getAVPlaybackState : SUCCESS');
122}).catch((err: BusinessError) => {
123  console.error(`getAVPlaybackState BusinessError: code: ${err.code}, message: ${err.message}`);
124});
125```
126
127## getAVMetadata<sup>10+</sup>
128
129getAVMetadata(): Promise\<AVMetadata>
130
131Obtains the session metadata. This API uses a promise to return the result.
132
133**Atomic service API**: This API can be used in atomic services since API version 12.
134
135**System capability**: SystemCapability.Multimedia.AVSession.Core
136
137**Return value**
138
139| Type                               | Description                         |
140| ----------------------------------- | ----------------------------- |
141| Promise<[AVMetadata](arkts-apis-avsession-i.md#avmetadata10)\> | Promise used to return the metadata obtained.|
142
143**Error codes**
144
145For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
146
147| ID| Error Message|
148| -------- | ---------------------------------------- |
149| 6600101  | Session service exception. |
150| 6600102  | The session does not exist. |
151| 6600103  | The session controller does not exist. |
152
153**Example**
154
155```ts
156import { BusinessError } from '@kit.BasicServicesKit';
157
158avsessionController.getAVMetadata().then((metadata: avSession.AVMetadata) => {
159  console.info(`GetAVMetadata : SUCCESS : assetId : ${metadata.assetId}`);
160}).catch((err: BusinessError) => {
161  console.error(`GetAVMetadata BusinessError: code: ${err.code}, message: ${err.message}`);
162});
163```
164
165## getAVMetadata<sup>10+</sup>
166
167getAVMetadata(callback: AsyncCallback\<AVMetadata>): void
168
169Obtains the session metadata. This API uses an asynchronous callback to return the result.
170
171**System capability**: SystemCapability.Multimedia.AVSession.Core
172
173**Parameters**
174
175| Name  | Type                                     | Mandatory| Description                      |
176| -------- | ----------------------------------------- | ---- | -------------------------- |
177| callback | AsyncCallback<[AVMetadata](arkts-apis-avsession-i.md#avmetadata10)\> | Yes  | Callback used to return the metadata obtained.|
178
179**Error codes**
180
181For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
182
183| ID| Error Message|
184| -------- | ---------------------------------------- |
185| 6600101  | Session service exception. |
186| 6600102  | The session does not exist. |
187| 6600103  | The session controller does not exist. |
188
189**Example**
190
191```ts
192import { BusinessError } from '@kit.BasicServicesKit';
193
194avsessionController.getAVMetadata((err: BusinessError, metadata: avSession.AVMetadata) => {
195  if (err) {
196    console.error(`GetAVMetadata BusinessError: code: ${err.code}, message: ${err.message}`);
197  } else {
198    console.info(`GetAVMetadata : SUCCESS : assetId : ${metadata.assetId}`);
199  }
200});
201```
202
203## getAVQueueTitle<sup>10+</sup>
204
205getAVQueueTitle(): Promise\<string>
206
207Obtains the name of the playlist. This API uses a promise to return the result.
208
209**Atomic service API**: This API can be used in atomic services since API version 12.
210
211**System capability**: SystemCapability.Multimedia.AVSession.Core
212
213**Return value**
214
215| Type            | Description                          |
216| ---------------- | ----------------------------- |
217| Promise<string\> | Promise used to return the playlist name.|
218
219**Error codes**
220
221For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
222
223| ID| Error Message|
224| -------- | ---------------------------------------- |
225| 6600101  | Session service exception. |
226| 6600102  | The session does not exist. |
227| 6600103  | The session controller does not exist. |
228
229**Example**
230
231```ts
232import { BusinessError } from '@kit.BasicServicesKit';
233
234avsessionController.getAVQueueTitle().then((title: string) => {
235  console.info(`GetAVQueueTitle : SUCCESS : title : ${title}`);
236}).catch((err: BusinessError) => {
237  console.error(`GetAVQueueTitle BusinessError: code: ${err.code}, message: ${err.message}`);
238});
239```
240
241## getAVQueueTitle<sup>10+</sup>
242
243getAVQueueTitle(callback: AsyncCallback\<string>): void
244
245Obtains the name of the playlist. This API uses an asynchronous callback to return the result.
246
247**System capability**: SystemCapability.Multimedia.AVSession.Core
248
249**Parameters**
250
251| Name  | Type                   | Mandatory| Description                     |
252| -------- | ---------------------- | ---- | ------------------------- |
253| callback | AsyncCallback<string\> | Yes  | Callback used to return the playlist name.|
254
255**Error codes**
256
257For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
258
259| ID| Error Message|
260| -------- | ---------------------------------------- |
261| 6600101  | Session service exception. |
262| 6600102  | The session does not exist. |
263| 6600103  | The session controller does not exist. |
264
265**Example**
266
267```ts
268import { BusinessError } from '@kit.BasicServicesKit';
269
270avsessionController.getAVQueueTitle((err: BusinessError, title: string) => {
271  if (err) {
272    console.error(`GetAVQueueTitle BusinessError: code: ${err.code}, message: ${err.message}`);
273  } else {
274    console.info(`GetAVQueueTitle : SUCCESS : title : ${title}`);
275  }
276});
277```
278
279## getAVQueueItems<sup>10+</sup>
280
281getAVQueueItems(): Promise\<Array\<AVQueueItem>>
282
283Obtains the information related to the items in the queue. This API uses a promise to return the result.
284
285**Atomic service API**: This API can be used in atomic services since API version 12.
286
287**System capability**: SystemCapability.Multimedia.AVSession.Core
288
289**Return value**
290
291| Type                                         | Description                          |
292| --------------------------------------------- | ----------------------------- |
293| Promise<Array<[AVQueueItem](arkts-apis-avsession-i.md#avqueueitem10)\>\> | Promise used to return the items in the queue.|
294
295**Error codes**
296
297For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
298
299| ID| Error Message|
300| -------- | ---------------------------------------- |
301| 6600101  | Session service exception. |
302| 6600102  | The session does not exist. |
303| 6600103  | The session controller does not exist. |
304
305**Example**
306
307```ts
308import { BusinessError } from '@kit.BasicServicesKit';
309
310avsessionController.getAVQueueItems().then((items: avSession.AVQueueItem[]) => {
311  console.info(`GetAVQueueItems : SUCCESS : length : ${items.length}`);
312}).catch((err: BusinessError) => {
313  console.error(`GetAVQueueItems BusinessError: code: ${err.code}, message: ${err.message}`);
314});
315```
316
317## getAVQueueItems<sup>10+</sup>
318
319getAVQueueItems(callback: AsyncCallback\<Array\<AVQueueItem>>): void
320
321Obtains the information related to the items in the playlist. This API uses an asynchronous callback to return the result.
322
323**System capability**: SystemCapability.Multimedia.AVSession.Core
324
325**Parameters**
326
327| Name  | Type                                                | Mandatory| Description                     |
328| -------- | --------------------------------------------------- | ---- | ------------------------- |
329| callback | AsyncCallback<Array<[AVQueueItem](arkts-apis-avsession-i.md#avqueueitem10)\>\> | Yes  | Callback used to return the items in the playlist.|
330
331**Error codes**
332
333For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
334
335| ID| Error Message|
336| -------- | ---------------------------------------- |
337| 6600101  | Session service exception. |
338| 6600102  | The session does not exist. |
339| 6600103  | The session controller does not exist. |
340
341**Example**
342
343```ts
344import { BusinessError } from '@kit.BasicServicesKit';
345
346avsessionController.getAVQueueItems((err: BusinessError, items: avSession.AVQueueItem[]) => {
347  if (err) {
348    console.error(`GetAVQueueItems BusinessError: code: ${err.code}, message: ${err.message}`);
349  } else {
350    console.info(`GetAVQueueItems : SUCCESS : length : ${items.length}`);
351  }
352});
353```
354
355## skipToQueueItem<sup>10+</sup>
356
357skipToQueueItem(itemId: number): Promise\<void>
358
359Sends the ID of an item in the playlist to the session for processing. The session can play the song. This API uses a promise to return the result.
360
361**Atomic service API**: This API can be used in atomic services since API version 12.
362
363**System capability**: SystemCapability.Multimedia.AVSession.Core
364
365**Parameters**
366
367| Name | Type   | Mandatory| Description                                       |
368| ------ | ------- | ---- | ------------------------------------------- |
369| itemId | number  | Yes  | ID of an item in the playlist.|
370
371**Return value**
372
373| Type          | Description                                                            |
374| -------------- | --------------------------------------------------------------- |
375| Promise\<void> | Promise used to return the result. If the item ID is sent, no value is returned; otherwise, an error object is returned.|
376
377**Error codes**
378
379For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
380
381| ID| Error Message|
382| -------- | ---------------------------------------- |
383| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. |
384| 6600101  | Session service exception. |
385| 6600102  | The session does not exist. |
386| 6600103  | The session controller does not exist. |
387
388**Example**
389
390```ts
391import { BusinessError } from '@kit.BasicServicesKit';
392
393let queueItemId = 0;
394avsessionController.skipToQueueItem(queueItemId).then(() => {
395  console.info('SkipToQueueItem successfully');
396}).catch((err: BusinessError) => {
397  console.error(`SkipToQueueItem BusinessError: code: ${err.code}, message: ${err.message}`);
398});
399```
400
401## skipToQueueItem<sup>10+</sup>
402
403skipToQueueItem(itemId: number, callback: AsyncCallback\<void>): void
404
405Sends the ID of an item in the playlist to the session for processing. The session can play the song. This API uses an asynchronous callback to return the result.
406
407**System capability**: SystemCapability.Multimedia.AVSession.Core
408
409**Parameters**
410
411| Name   | Type                 | Mandatory| Description                                                       |
412| -------- | --------------------- | ---- | ----------------------------------------------------------- |
413| itemId   | number                | Yes  | ID of an item in the playlist.               |
414| callback | AsyncCallback\<void>  | Yes  | Callback used to return the result. If the setting is successful, **err** is **undefined**; otherwise, **err** is an error object.|
415
416**Error codes**
417
418For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
419
420| ID| Error Message|
421| -------- | ---------------------------------------- |
422| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. |
423| 6600101  | Session service exception. |
424| 6600102  | The session does not exist. |
425| 6600103  | The session controller does not exist. |
426
427**Example**
428
429```ts
430import { BusinessError } from '@kit.BasicServicesKit';
431
432let queueItemId = 0;
433avsessionController.skipToQueueItem(queueItemId, (err: BusinessError) => {
434  if (err) {
435    console.error(`SkipToQueueItem BusinessError: code: ${err.code}, message: ${err.message}`);
436  } else {
437    console.info('SkipToQueueItem successfully');
438  }
439});
440```
441
442## getOutputDevice<sup>10+</sup>
443
444getOutputDevice(): Promise\<OutputDeviceInfo>
445
446Obtains the output device information. This API uses a promise to return the result.
447
448**Atomic service API**: This API can be used in atomic services since API version 12.
449
450**System capability**: SystemCapability.Multimedia.AVSession.Core
451
452**Return value**
453
454| Type                                           | Description                             |
455| ----------------------------------------------- | --------------------------------- |
456| Promise<[OutputDeviceInfo](arkts-apis-avsession-i.md#outputdeviceinfo10)\> | Promise used to return the information obtained.|
457
458**Error codes**
459
460For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
461
462| ID| Error Message|
463| -------- | ---------------------------------------- |
464| 600101  | Session service exception. |
465| 600103  | The session controller does not exist. |
466
467**Example**
468
469```ts
470import { BusinessError } from '@kit.BasicServicesKit';
471
472avsessionController.getOutputDevice().then((deviceInfo: avSession.OutputDeviceInfo) => {
473  console.info('GetOutputDevice : SUCCESS');
474}).catch((err: BusinessError) => {
475  console.error(`GetOutputDevice BusinessError: code: ${err.code}, message: ${err.message}`);
476});
477```
478
479## getOutputDevice<sup>10+</sup>
480
481getOutputDevice(callback: AsyncCallback\<OutputDeviceInfo>): void
482
483Obtains the output device information. This API uses an asynchronous callback to return the result.
484
485**System capability**: SystemCapability.Multimedia.AVSession.Core
486
487**Parameters**
488
489| Name  | Type                                                 | Mandatory| Description                          |
490| -------- | ----------------------------------------------------- | ---- | ------------------------------ |
491| callback | AsyncCallback<[OutputDeviceInfo](arkts-apis-avsession-i.md#outputdeviceinfo10)\> | Yes  | Callback used to return the information obtained.|
492
493**Error codes**
494
495For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
496
497| ID| Error Message|
498| -------- | ---------------------------------------- |
499| 600101  | Session service exception. |
500| 600103  | The session controller does not exist. |
501
502**Example**
503
504```ts
505import { BusinessError } from '@kit.BasicServicesKit';
506
507avsessionController.getOutputDevice((err: BusinessError, deviceInfo: avSession.OutputDeviceInfo) => {
508  if (err) {
509    console.error(`GetOutputDevice BusinessError: code: ${err.code}, message: ${err.message}`);
510  } else {
511    console.info('GetOutputDevice : SUCCESS');
512  }
513});
514```
515
516## sendAVKeyEvent<sup>10+</sup>
517
518sendAVKeyEvent(event: KeyEvent): Promise\<void>
519
520Sends a key event to the session corresponding to this controller. This API uses a promise to return the result.
521
522**Atomic service API**: This API can be used in atomic services since API version 12.
523
524**System capability**: SystemCapability.Multimedia.AVSession.Core
525
526**Parameters**
527
528| Name| Type                                                        | Mandatory| Description      |
529| ------ | ------------------------------------------------------------ | ---- | ---------- |
530| event  | [KeyEvent](../apis-input-kit/js-apis-keyevent.md) | Yes  | Key event.|
531
532**Error codes**
533
534For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
535
536| ID| Error Message|
537| -------- | ---------------------------------------- |
538| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. |
539| 600101  | Session service exception. |
540| 600102  | The session does not exist. |
541| 600103  | The session controller does not exist. |
542| 600105  | Invalid session command. |
543| 600106  | The session is not activated. |
544
545**Return value**
546
547| Type          | Description                         |
548| -------------- | ----------------------------- |
549| Promise\<void> | Promise used to return the result. If the event is sent, no value is returned; otherwise, an error object is returned.|
550
551**Example**
552
553```ts
554import { Key, KeyEvent } from '@kit.InputKit';
555import { BusinessError } from '@kit.BasicServicesKit';
556
557let keyItem: Key = {code:0x49, pressedTime:2, deviceId:0};
558let event: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};
559
560
561avsessionController.sendAVKeyEvent(event).then(() => {
562  console.info('SendAVKeyEvent Successfully');
563}).catch((err: BusinessError) => {
564  console.error(`SendAVKeyEvent BusinessError: code: ${err.code}, message: ${err.message}`);
565});
566```
567
568## sendAVKeyEvent<sup>10+</sup>
569
570sendAVKeyEvent(event: KeyEvent, callback: AsyncCallback\<void>): void
571
572Sends a key event to the session corresponding to this controller. This API uses an asynchronous callback to return the result.
573
574**System capability**: SystemCapability.Multimedia.AVSession.Core
575
576**Parameters**
577
578| Name  | Type                                                        | Mandatory| Description      |
579| -------- | ------------------------------------------------------------ | ---- | ---------- |
580| event    | [KeyEvent](../apis-input-kit/js-apis-keyevent.md) | Yes  | Key event.|
581| callback | AsyncCallback\<void>                                         | Yes  | Callback used to return the result. If the event is sent, **err** is **undefined**; otherwise, **err** is an error object.|
582
583**Error codes**
584
585For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
586
587| ID| Error Message|
588| -------- | ---------------------------------------- |
589| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. |
590| 600101  | Session service exception. |
591| 600102  | The session does not exist. |
592| 600103  | The session controller does not exist. |
593| 600105  | Invalid session command. |
594| 600106  | The session is not activated. |
595
596**Example**
597
598```ts
599import { Key, KeyEvent } from '@kit.InputKit';
600import { BusinessError } from '@kit.BasicServicesKit';
601
602let keyItem: Key = {code:0x49, pressedTime:2, deviceId:0};
603let event: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};
604avsessionController.sendAVKeyEvent(event, (err: BusinessError) => {
605  if (err) {
606    console.error(`SendAVKeyEvent BusinessError: code: ${err.code}, message: ${err.message}`);
607  } else {
608    console.info('SendAVKeyEvent Successfully');
609  }
610});
611```
612
613## getLaunchAbility<sup>10+</sup>
614
615getLaunchAbility(): Promise\<WantAgent>
616
617Obtains the WantAgent object saved by the application in the session. This API uses a promise to return the result.
618
619**Atomic service API**: This API can be used in atomic services since API version 12.
620
621**System capability**: SystemCapability.Multimedia.AVSession.Core
622
623**Return value**
624
625| Type                                                   | Description                                                        |
626| ------------------------------------------------------- | ------------------------------------------------------------ |
627| Promise<[WantAgent](../apis-ability-kit/js-apis-app-ability-wantAgent.md)\> | Promise used to return the object saved by calling [setLaunchAbility](arkts-apis-avsession-AVSession.md#setlaunchability10). The object includes the application property, such as the bundle name, ability name, and device ID.|
628
629**Error codes**
630
631For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
632
633| ID| Error Message|
634| -------- | ---------------------------------------- |
635| 6600101  | Session service exception. |
636| 6600102  | The session does not exist. |
637| 6600103  | The session controller does not exist. |
638
639**Example**
640
641```ts
642import { BusinessError } from '@kit.BasicServicesKit';
643
644avsessionController.getLaunchAbility().then((agent: object) => {
645  console.info(`GetLaunchAbility : SUCCESS : wantAgent : ${agent}`);
646}).catch((err: BusinessError) => {
647  console.error(`GetLaunchAbility BusinessError: code: ${err.code}, message: ${err.message}`);
648});
649```
650
651## getLaunchAbility<sup>10+</sup>
652
653getLaunchAbility(callback: AsyncCallback\<WantAgent>): void
654
655Obtains the WantAgent object saved by the application in the session. This API uses an asynchronous callback to return the result.
656
657**System capability**: SystemCapability.Multimedia.AVSession.Core
658
659**Parameters**
660
661| Name  | Type                                                        | Mandatory| Description                                                        |
662| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
663| callback | AsyncCallback<[WantAgent](../apis-ability-kit/js-apis-app-ability-wantAgent.md)\> | Yes  | Callback used to return the object saved by calling [setLaunchAbility](arkts-apis-avsession-AVSession.md#setlaunchability10). The object includes the application property, such as the bundle name, ability name, and device ID.|
664
665**Error codes**
666
667For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
668
669| ID| Error Message|
670| -------- | ---------------------------------------- |
671| 6600101  | Session service exception. |
672| 6600102  | The session does not exist. |
673| 6600103  | The session controller does not exist. |
674
675**Example**
676
677```ts
678import { BusinessError } from '@kit.BasicServicesKit';
679
680avsessionController.getLaunchAbility((err: BusinessError, agent: object) => {
681  if (err) {
682    console.error(`GetLaunchAbility BusinessError: code: ${err.code}, message: ${err.message}`);
683  } else {
684    console.info(`GetLaunchAbility : SUCCESS : wantAgent : ${agent}`);
685  }
686});
687```
688
689## getRealPlaybackPositionSync<sup>10+</sup>
690
691getRealPlaybackPositionSync(): number
692
693Obtains the playback position.
694
695**Atomic service API**: This API can be used in atomic services since API version 12.
696
697**System capability**: SystemCapability.Multimedia.AVSession.Core
698
699**Return value**
700
701| Type  | Description              |
702| ------ | ------------------ |
703| number | Playback position, in milliseconds.|
704
705**Error codes**
706
707For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
708
709| ID| Error Message|
710| -------- | ---------------------------------------- |
711| 6600101  | Session service exception. |
712| 6600103  | The session controller does not exist. |
713
714**Example**
715
716```ts
717let time: number = avsessionController.getRealPlaybackPositionSync();
718```
719
720## isActive<sup>10+</sup>
721
722isActive(): Promise\<boolean>
723
724Checks whether the session is activated. This API uses a promise to return the result.
725
726**Atomic service API**: This API can be used in atomic services since API version 12.
727
728**System capability**: SystemCapability.Multimedia.AVSession.Core
729
730**Return value**
731
732| Type             | Description                                                        |
733| ----------------- | ------------------------------------------------------------ |
734| Promise<boolean\> | Promise used to return the activation state. If the session is activated, **true** is returned; otherwise, **false** is returned.|
735
736**Error codes**
737
738For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
739
740| ID| Error Message|
741| -------- | ---------------------------------------- |
742| 6600101  | Session service exception. |
743| 6600102  | The session does not exist. |
744| 6600103  | The session controller does not exist. |
745
746**Example**
747
748```ts
749import { BusinessError } from '@kit.BasicServicesKit';
750
751avsessionController.isActive().then((isActive: boolean) => {
752  console.info(`IsActive : SUCCESS : isactive : ${isActive}`);
753}).catch((err: BusinessError) => {
754  console.error(`IsActive BusinessError: code: ${err.code}, message: ${err.message}`);
755});
756```
757
758## isActive<sup>10+</sup>
759
760isActive(callback: AsyncCallback\<boolean>): void
761
762Checks whether the session is activated. This API uses an asynchronous callback to return the result.
763
764**System capability**: SystemCapability.Multimedia.AVSession.Core
765
766**Parameters**
767
768| Name  | Type                   | Mandatory| Description                                                        |
769| -------- | ----------------------- | ---- | ------------------------------------------------------------ |
770| callback | AsyncCallback<boolean\> | Yes  | Callback used to return the activation state. If the session is activated, **true** is returned; otherwise, **false** is returned.|
771
772**Error codes**
773
774For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
775
776| ID| Error Message|
777| -------- | ---------------------------------------- |
778| 6600101  | Session service exception. |
779| 6600102  | The session does not exist. |
780| 6600103  | The session controller does not exist. |
781
782**Example**
783
784```ts
785import { BusinessError } from '@kit.BasicServicesKit';
786
787avsessionController.isActive((err: BusinessError, isActive: boolean) => {
788  if (err) {
789    console.error(`IsActive BusinessError: code: ${err.code}, message: ${err.message}`);
790  } else {
791    console.info(`IsActive : SUCCESS : isactive : ${isActive}`);
792  }
793});
794```
795
796## destroy<sup>10+</sup>
797
798destroy(): Promise\<void>
799
800Destroys this controller. A controller can no longer be used after being destroyed. This API uses a promise to return the result.
801
802**Atomic service API**: This API can be used in atomic services since API version 12.
803
804**System capability**: SystemCapability.Multimedia.AVSession.Core
805
806**Return value**
807
808| Type          | Description                         |
809| -------------- | ----------------------------- |
810| Promise\<void> | Promise used to return the result. If the controller is destroyed, no value is returned; otherwise, an error object is returned.|
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| 6600101  | Session service exception. |
819| 6600103  | The session controller does not exist. |
820
821**Example**
822
823```ts
824import { BusinessError } from '@kit.BasicServicesKit';
825
826avsessionController.destroy().then(() => {
827  console.info('Destroy : SUCCESS ');
828}).catch((err: BusinessError) => {
829  console.error(`Destroy BusinessError: code: ${err.code}, message: ${err.message}`);
830});
831```
832
833## destroy<sup>10+</sup>
834
835destroy(callback: AsyncCallback\<void>): void
836
837Destroys this controller. A controller can no longer be used after being destroyed. This API uses an asynchronous callback to return the result.
838
839**System capability**: SystemCapability.Multimedia.AVSession.Core
840
841**Parameters**
842
843| Name  | Type                | Mandatory| Description      |
844| -------- | -------------------- | ---- | ---------- |
845| callback | AsyncCallback\<void> | Yes  | Callback used to return the result. If the controller is destroyed, **err** is **undefined**; otherwise, **err** is an error object.|
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| 6600101  | Session service exception. |
854| 6600103  | The session controller does not exist. |
855
856**Example**
857
858```ts
859import { BusinessError } from '@kit.BasicServicesKit';
860
861avsessionController.destroy((err: BusinessError) => {
862  if (err) {
863    console.error(`Destroy BusinessError: code: ${err.code}, message: ${err.message}`);
864  } else {
865    console.info('Destroy : SUCCESS ');
866  }
867});
868```
869
870## getValidCommands<sup>10+</sup>
871
872getValidCommands(): Promise\<Array\<AVControlCommandType>>
873
874Obtains valid commands supported by the session. This API uses a promise to return the result.
875
876**Atomic service API**: This API can be used in atomic services since API version 12.
877
878**System capability**: SystemCapability.Multimedia.AVSession.Core
879
880**Return value**
881
882| Type                                                        | Description                             |
883| ------------------------------------------------------------ | --------------------------------- |
884| Promise<Array<[AVControlCommandType](arkts-apis-avsession-t.md#avcontrolcommandtype10)\>\> | Promise used to return a set of valid commands.|
885
886**Error codes**
887
888For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
889
890| ID| Error Message|
891| -------- | ---------------------------------------- |
892| 6600101  | Session service exception. |
893| 6600102  | The session does not exist. |
894| 6600103  | The session controller does not exist. |
895
896**Example**
897
898```ts
899import { BusinessError } from '@kit.BasicServicesKit';
900
901avsessionController.getValidCommands().then((validCommands: avSession.AVControlCommandType[]) => {
902  console.info(`GetValidCommands : SUCCESS : size : ${validCommands.length}`);
903}).catch((err: BusinessError) => {
904  console.error(`GetValidCommands BusinessError: code: ${err.code}, message: ${err.message}`);
905});
906```
907
908## getValidCommands<sup>10+</sup>
909
910getValidCommands(callback: AsyncCallback\<Array\<AVControlCommandType>>): void
911
912Obtains valid commands supported by the session. This API uses an asynchronous callback to return the result.
913
914**System capability**: SystemCapability.Multimedia.AVSession.Core
915
916**Parameters**
917
918| Name  | Type                                                        | Mandatory| Description                          |
919| -------- | ------------------------------------------------------------ | ---- | ------------------------------ |
920| callback | AsyncCallback\<Array\<[AVControlCommandType](arkts-apis-avsession-t.md#avcontrolcommandtype10)\>\> | Yes  | Callback used to return a set of valid commands.|
921
922**Error codes**
923
924For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
925
926| ID| Error Message|
927| -------- | ---------------------------------------- |
928| 6600101  | Session service exception. |
929| 6600102  | The session does not exist. |
930| 6600103  | The session controller does not exist. |
931
932**Example**
933
934```ts
935import { BusinessError } from '@kit.BasicServicesKit';
936
937avsessionController.getValidCommands((err: BusinessError, validCommands: avSession.AVControlCommandType[]) => {
938  if (err) {
939    console.error(`GetValidCommands BusinessError: code: ${err.code}, message: ${err.message}`);
940  } else {
941    console.info(`GetValidCommands : SUCCESS : size : ${validCommands.length}`);
942  }
943});
944```
945
946## sendControlCommand<sup>10+</sup>
947
948sendControlCommand(command: AVControlCommand): Promise\<void>
949
950Sends a control command to the session through the controller. This API uses a promise to return the result.
951
952> **NOTE**
953>
954> Before using **sendControlCommand**, the controller must ensure that the corresponding listeners are registered for the media session. For details about how to register the listeners, see [on'play'](arkts-apis-avsession-AVSession.md#onplay10), [on'pause'](arkts-apis-avsession-AVSession.md#onpause10), and the like.
955
956**Atomic service API**: This API can be used in atomic services since API version 12.
957
958**System capability**: SystemCapability.Multimedia.AVSession.Core
959
960**Parameters**
961
962| Name   | Type                                 | Mandatory| Description                          |
963| ------- | ------------------------------------- | ---- | ------------------------------ |
964| command | [AVControlCommand](arkts-apis-avsession-i.md#avcontrolcommand10) | Yes  | Command to send.|
965
966**Return value**
967
968| Type          | Description                         |
969| -------------- | ----------------------------- |
970| Promise\<void> | Promise used to return the result. If the command is sent, no value is returned; otherwise, an error object is returned.|
971
972**Error codes**
973
974For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
975
976| ID| Error Message|
977| -------- | ---------------------------------------- |
978| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. |
979| 6600101  | Session service exception. |
980| 6600102  | The session does not exist. |
981| 6600103  | The session controller does not exist. |
982| 6600105  | Invalid session command. |
983| 6600106  | The session is not activated. |
984| 6600107  | Too many commands or events. |
985
986**Example**
987
988```ts
989import { BusinessError } from '@kit.BasicServicesKit';
990
991let avCommand: avSession.AVControlCommand = {command:'play'};
992avsessionController.sendControlCommand(avCommand).then(() => {
993  console.info('SendControlCommand successfully');
994}).catch((err: BusinessError) => {
995  console.error(`SendControlCommand BusinessError: code: ${err.code}, message: ${err.message}`);
996});
997```
998
999## sendControlCommand<sup>10+</sup>
1000
1001sendControlCommand(command: AVControlCommand, callback: AsyncCallback\<void>): void
1002
1003Sends a control command to the session through the controller. This API uses an asynchronous callback to return the result.
1004
1005> **NOTE**
1006>
1007> Before using **sendControlCommand**, the controller must ensure that the corresponding listeners are registered for the media session. For details about how to register the listeners, see [on'play'](arkts-apis-avsession-AVSession.md#onplay10), [on'pause'](arkts-apis-avsession-AVSession.md#onpause10), and the like.
1008
1009**System capability**: SystemCapability.Multimedia.AVSession.Core
1010
1011**Parameters**
1012
1013| Name  | Type                                 | Mandatory| Description                          |
1014| -------- | ------------------------------------- | ---- | ------------------------------ |
1015| command  | [AVControlCommand](arkts-apis-avsession-i.md#avcontrolcommand10) | Yes  | Command to send.|
1016| callback | AsyncCallback\<void>                  | Yes  | Callback used to return the result. If the command is sent, **err** is **undefined**; otherwise, **err** is an error object.                    |
1017
1018**Error codes**
1019
1020For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1021
1022| ID| Error Message|
1023| -------- | ------------------------------- |
1024| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. |
1025| 6600101  | Session service exception. |
1026| 6600102  | The session does not exist.     |
1027| 6600103  | The session controller does not exist.   |
1028| 6600105  | Invalid session command. |
1029| 6600106  | The session is not activated.                |
1030| 6600107  | Too many commands or events. |
1031
1032**Example**
1033
1034```ts
1035import { BusinessError } from '@kit.BasicServicesKit';
1036
1037let avCommand: avSession.AVControlCommand = {command:'play'};
1038avsessionController.sendControlCommand(avCommand, (err: BusinessError) => {
1039  if (err) {
1040    console.error(`SendControlCommand BusinessError: code: ${err.code}, message: ${err.message}`);
1041  } else {
1042    console.info('SendControlCommand successfully');
1043  }
1044});
1045```
1046
1047## sendCommonCommand<sup>10+</sup>
1048
1049sendCommonCommand(command: string, args: {[key: string]: Object}): Promise\<void>
1050
1051Sends a custom control command to the session through the controller. This API uses a promise to return the result.
1052
1053**Atomic service API**: This API can be used in atomic services since API version 12.
1054
1055**System capability**: SystemCapability.Multimedia.AVSession.Core
1056
1057**Parameters**
1058
1059| Name   | Type                                 | Mandatory| Description                          |
1060| ------- | ------------------------------------- | ---- | ------------------------------ |
1061| command | string | Yes  | Name of the custom control command.|
1062| args | {[key: string]: Object} | Yes  | Parameters in key-value pair format carried in the custom control command.|
1063
1064> **NOTE**
1065>
1066> The **args** parameter supports the following data types: string, number, Boolean, object, array, and file descriptor. For details, see [@ohos.app.ability.Want(Want)](../apis-ability-kit/js-apis-app-ability-want.md).
1067
1068**Return value**
1069
1070| Type          | Description                         |
1071| -------------- | ----------------------------- |
1072| Promise\<void> | Promise used to return the result. If the command is sent, no value is returned; otherwise, an error object is returned.|
1073
1074**Error codes**
1075
1076For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1077
1078| ID| Error Message|
1079| -------- | ---------------------------------------- |
1080| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed. |
1081| 6600101  | Session service exception. |
1082| 6600102  | The session does not exist. |
1083| 6600103  | The session controller does not exist. |
1084| 6600105  | Invalid session command. |
1085| 6600106  | The session is not activated. |
1086| 6600107  | Too many commands or events. |
1087
1088**Example**
1089
1090```ts
1091import { BusinessError } from '@kit.BasicServicesKit';
1092import { avSession } from '@kit.AVSessionKit';
1093
1094let tag: string = "createNewSession";
1095let sessionId: string = "";
1096let controller:avSession.AVSessionController | undefined = undefined;
1097avSession.createAVSession(context, tag, "audio").then(async (data:avSession.AVSession)=> {
1098  currentAVSession = data;
1099  sessionId = currentAVSession.sessionId;
1100  controller = await currentAVSession.getController();
1101  console.info('CreateAVSession : SUCCESS :sessionid = ${sessionid}');
1102}).catch((err: BusinessError) => {
1103  console.error('CreateAVSession BusinessError:code: ${err.code}, message: ${err.message}')
1104});
1105let commandName = "my_command";
1106if (controller !== undefined) {
1107  (controller as avSession.AVSessionController).sendCommonCommand(commandName, {command : "This is my command"}).then(() => {
1108    console.info('SendCommonCommand successfully');
1109  }).catch((err: BusinessError) => {
1110    console.error(`SendCommonCommand BusinessError: code: ${err.code}, message: ${err.message}`);
1111  })
1112}
1113```
1114
1115## sendCommonCommand<sup>10+</sup>
1116
1117sendCommonCommand(command: string, args: {[key: string]: Object}, callback: AsyncCallback\<void>): void
1118
1119Sends a custom control command to the session through the controller. This API uses an asynchronous callback to return the result.
1120
1121**System capability**: SystemCapability.Multimedia.AVSession.Core
1122
1123**Parameters**
1124
1125| Name   | Type                                 | Mandatory| Description                          |
1126| ------- | ------------------------------------- | ---- | ------------------------------ |
1127| command | string | Yes  | Name of the custom control command.|
1128| args | {[key: string]: Object} | Yes  | Parameters in key-value pair format carried in the custom control command.|
1129| callback | AsyncCallback\<void>                  | Yes  | Callback used to return the result. If the command is sent, **err** is **undefined**; otherwise, **err** is an error object.                    |
1130
1131> **NOTE**
1132> The **args** parameter supports the following data types: string, number, Boolean, object, array, and file descriptor. For details, see [@ohos.app.ability.Want(Want)](../apis-ability-kit/js-apis-app-ability-want.md).
1133
1134**Error codes**
1135
1136For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1137
1138| ID| Error Message|
1139| -------- | ------------------------------- |
1140| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.|
1141| 6600101  | Session service exception. |
1142| 6600102  | The session does not exist.     |
1143| 6600103  | The session controller does not exist.   |
1144| 6600105  | Invalid session command. |
1145| 6600106  | The session is not activated.                |
1146| 6600107  | Too many commands or events. |
1147
1148**Example**
1149
1150```ts
1151import { BusinessError } from '@kit.BasicServicesKit';
1152import { avSession } from '@kit.AVSessionKit';
1153
1154let tag: string = "createNewSession";
1155let sessionId: string = "";
1156let controller:avSession.AVSessionController | undefined = undefined;
1157avSession.createAVSession(context, tag, "audio").then(async (data:avSession.AVSession)=> {
1158  currentAVSession = data;
1159  sessionId = currentAVSession.sessionId;
1160  controller = await currentAVSession.getController();
1161  console.info('CreateAVSession : SUCCESS :sessionid = ${sessionid}');
1162}).catch((err: BusinessError) => {
1163  console.error('CreateAVSession BusinessError:code: ${err.code}, message: ${err.message}')
1164});
1165let commandName = "my_command";
1166if (controller !== undefined) {
1167  (controller as avSession.AVSessionController).sendCommonCommand(commandName, {command : "This is my command"}, (err: BusinessError) => {
1168    if (err) {
1169      console.error(`SendCommonCommand BusinessError: code: ${err.code}, message: ${err.message}`);
1170    }
1171  })
1172}
1173```
1174
1175## sendCustomData<sup>20+</sup>
1176
1177sendCustomData(data: Record\<string, Object>): Promise\<void>
1178
1179Sends custom data to the remote device. This API uses a promise to return the result.
1180
1181**Atomic service API**: This API can be used in atomic services since API version 20.
1182
1183**System capability**: SystemCapability.Multimedia.AVSession.AVCast
1184
1185**Parameters**
1186
1187| Name| Type                  | Mandatory| Description                                                        |
1188| ------ | ---------------------- | ---- | ------------------------------------------------------------ |
1189| data   | Record\<string, Object> | Yes  | Custom data filled by the application. Only objects with the key **'customData'** and of the type string are parsed on the server.|
1190
1191**Return value**
1192
1193| Type          | Description                         |
1194| -------------- | ----------------------------- |
1195| Promise\<void> | Promise that returns no value.|
1196
1197**Error codes**
1198
1199For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1200
1201| ID| Error Message                                                    |
1202| -------- | ------------------------------------------------------------ |
1203| 6600101  | Session service exception. |
1204| 6600102  | The session does not exist.                                  |
1205| 6600103  | The session controller does not exist.                       |
1206
1207**Example**
1208
1209```ts
1210import { BusinessError } from '@kit.BasicServicesKit';
1211import { avSession } from '@kit.AVSessionKit';
1212
1213let tag: string = "createNewSession";
1214let sessionId: string = "";
1215let controller:avSession.AVSessionController | undefined = undefined;
1216avSession.createAVSession(context, tag, "audio").then(async (data:avSession.AVSession)=> {
1217  currentAVSession = data;
1218  sessionId = currentAVSession.sessionId;
1219  controller = await currentAVSession.getController();
1220  console.info('CreateAVSession : SUCCESS :sessionid = ${sessionid}');
1221}).catch((err: BusinessError) => {
1222  console.error('CreateAVSession BusinessError:code: ${err.code}, message: ${err.message}')
1223});
1224
1225if (controller !== undefined) {
1226  (controller as avSession.AVSessionController).sendCustomData({customData : "This is my data"})
1227}
1228```
1229
1230## getExtras<sup>10+</sup>
1231
1232getExtras(): Promise\<{[key: string]: Object}>
1233
1234Obtains the custom media packet set by the provider. This API uses a promise to return the result.
1235
1236**Atomic service API**: This API can be used in atomic services since API version 12.
1237
1238**System capability**: SystemCapability.Multimedia.AVSession.Core
1239
1240**Return value**
1241
1242| Type                               | Description                         |
1243| ----------------------------------- | ----------------------------- |
1244| Promise<{[key: string]: Object}\>   | Promise used to return the custom media packet. The content of the packet is the same as that set in **setExtras**.|
1245
1246**Error codes**
1247
1248For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1249
1250| ID| Error Message|
1251| -------- | ---------------------------------------- |
1252| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
1253| 6600101  | Session service exception. |
1254| 6600102  | The session does not exist. |
1255| 6600103  | The session controller does not exist. |
1256| 6600105  | Invalid session command. |
1257| 6600107  | Too many commands or events. |
1258
1259**Example**
1260
1261```ts
1262import { BusinessError } from '@kit.BasicServicesKit';
1263import { avSession } from '@kit.AVSessionKit';
1264
1265let tag: string = "createNewSession";
1266let sessionId: string = "";
1267let controller:avSession.AVSessionController | undefined = undefined;
1268avSession.createAVSession(context, tag, "audio").then(async (data:avSession.AVSession)=> {
1269  currentAVSession = data;
1270  sessionId = currentAVSession.sessionId;
1271  controller = await currentAVSession.getController();
1272  console.info('CreateAVSession : SUCCESS :sessionid = ${sessionid}');
1273}).catch((err: BusinessError) => {
1274  console.error('CreateAVSession BusinessError:code: ${err.code}, message: ${err.message}')
1275});
1276if (controller !== undefined) {
1277  (controller as avSession.AVSessionController).getExtras().then((extras) => {
1278    console.info(`getExtras : SUCCESS : ${extras}`);
1279  }).catch((err: BusinessError) => {
1280    console.error(`getExtras BusinessError: code: ${err.code}, message: ${err.message}`);
1281  });
1282}
1283```
1284
1285## getExtras<sup>10+</sup>
1286
1287getExtras(callback: AsyncCallback\<{[key: string]: Object}>): void
1288
1289Obtains the custom media packet set by the provider. This API uses an asynchronous callback to return the result.
1290
1291**System capability**: SystemCapability.Multimedia.AVSession.Core
1292
1293**Parameters**
1294
1295| Name  | Type                                     | Mandatory| Description                      |
1296| -------- | ----------------------------------------- | ---- | -------------------------- |
1297| callback | AsyncCallback<{[key: string]: Object}\> | Yes  | Callback used to return the custom media packet. The content of the packet is the same as that set in **setExtras**.|
1298
1299**Error codes**
1300
1301For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1302
1303| ID| Error Message|
1304| -------- | ---------------------------------------- |
1305| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed. |
1306| 6600101  | Session service exception. |
1307| 6600102  | The session does not exist. |
1308| 6600103  | The session controller does not exist. |
1309| 6600105  | Invalid session command. |
1310| 6600107  |Too many commands or events. |
1311
1312**Example**
1313
1314```ts
1315import { BusinessError } from '@kit.BasicServicesKit';
1316import { avSession } from '@kit.AVSessionKit';
1317
1318let tag: string = "createNewSession";
1319let sessionId: string = "";
1320let controller:avSession.AVSessionController | undefined = undefined;
1321avSession.createAVSession(context, tag, "audio").then(async (data:avSession.AVSession)=> {
1322  currentAVSession = data;
1323  sessionId = currentAVSession.sessionId;
1324  controller = await currentAVSession.getController();
1325  console.info('CreateAVSession : SUCCESS :sessionid = ${sessionid}');
1326}).catch((err: BusinessError) => {
1327  console.error('CreateAVSession BusinessError:code: ${err.code}, message: ${err.message}')
1328});
1329if (controller !== undefined) {
1330  (controller as avSession.AVSessionController).getExtras((err, extras) => {
1331    if (err) {
1332      console.error(`getExtras BusinessError: code: ${err.code}, message: ${err.message}`);
1333    } else {
1334      console.info(`getExtras : SUCCESS : ${extras}`);
1335    }
1336  });
1337}
1338```
1339
1340## getExtrasWithEvent<sup>18+</sup>
1341
1342getExtrasWithEvent(extraEvent: string): Promise\<ExtraInfo>
1343
1344Obtains the custom media packet set by the remote distributed media provider based on the remote distributed event type. This API uses a promise to return the result.
1345
1346**System capability**: SystemCapability.Multimedia.AVSession.Core
1347
1348**Parameters**
1349
1350| Name  | Type                                     | Mandatory| Description                      |
1351| -------- | ----------------------------------------- | ---- | -------------------------- |
1352| extraEvent | string | Yes| Remote distributed event type.<br>Currently, the following event types are supported:<br>**'AUDIO_GET_VOLUME'**: obtains the volume of the remote device.<br>**'AUDIO_GET_AVAILABLE_DEVICES'**: obtains all remote devices that can be connected.<br>**'AUDIO_GET_PREFERRED_OUTPUT_DEVICE_FOR_RENDERER_INFO'**: obtains the actual remote audio device.|
1353
1354**Return value**
1355
1356| Type                               | Description                         |
1357| ----------------------------------- | ----------------------------- |
1358| Promise<[ExtraInfo](arkts-apis-avsession-t.md#extrainfo18)\>   | Promise used to return the custom media packet set by the remote distributed media provider.<br>The **ExtraInfo** parameter supports the following data types: string, number, Boolean, object, array, and file descriptor. For details, see [@ohos.app.ability.Want(Want)](../apis-ability-kit/js-apis-app-ability-want.md).|
1359
1360**Error codes**
1361
1362For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1363
1364| ID| Error Message|
1365| -------- | ---------------------------------------- |
1366| 6600101  | Session service exception. |
1367| 6600102  | The session does not exist. |
1368| 6600103  | The session controller does not exist. |
1369| 6600105  | Invalid session command. |
1370
1371**Example**
1372
1373```ts
1374import { BusinessError } from '@kit.BasicServicesKit';
1375
1376let controller: avSession.AVSessionController | ESObject;
1377const COMMON_COMMAND_STRING_1 = 'AUDIO_GET_VOLUME';
1378const COMMON_COMMAND_STRING_2 = 'AUDIO_GET_AVAILABLE_DEVICES';
1379const COMMON_COMMAND_STRING_3 = 'AUDIO_GET_PREFERRED_OUTPUT_DEVICE_FOR_RENDERER_INFO';
1380if (controller !== undefined) {
1381  controller.getExtrasWithEvent(COMMON_COMMAND_STRING_1).then(() => {
1382    console.info(`${[COMMON_COMMAND_STRING_1]}`);
1383  }).catch((err: BusinessError) => {
1384    console.error(`getExtrasWithEvent failed with err: ${err.code}, ${err.message}`);
1385  })
1386
1387  controller.getExtrasWithEvent(COMMON_COMMAND_STRING_2).then(() => {
1388    console.info(`${[COMMON_COMMAND_STRING_2]}`);
1389  }).catch((err: BusinessError) => {
1390    console.error(`getExtrasWithEvent failed with err: ${err.code}, ${err.message}`);
1391  })
1392
1393  controller.getExtrasWithEvent(COMMON_COMMAND_STRING_3).then(() => {
1394    console.info(`${[COMMON_COMMAND_STRING_3]}`);
1395  }).catch((err: BusinessError) => {
1396    console.error(`getExtrasWithEvent failed with err: ${err.code}, ${err.message}`);
1397  })
1398}
1399```
1400
1401## on('metadataChange')<sup>10+</sup>
1402
1403on(type: 'metadataChange', filter: Array\<keyof AVMetadata> | 'all', callback: (data: AVMetadata) => void)
1404
1405Subscribes to metadata change events.
1406
1407Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.
1408
1409**Atomic service API**: This API can be used in atomic services since API version 12.
1410
1411**System capability**: SystemCapability.Multimedia.AVSession.Core
1412
1413**Parameters**
1414
1415| Name  | Type                                                        | Mandatory| Description                                                        |
1416| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
1417| type     | string                                                       | Yes  | Event type. The event **'metadataChange'** is triggered when the session metadata changes.|
1418| filter   | Array\<keyof&nbsp;[AVMetadata](arkts-apis-avsession-i.md#avmetadata10)\>&nbsp;&#124;&nbsp;'all' | Yes  | The value **'all'** indicates that any metadata field change will trigger the event, and **Array<keyof&nbsp;[AVMetadata](arkts-apis-avsession-i.md#avmetadata10)\>** indicates that only changes to the listed metadata field will trigger the event.|
1419| callback | (data: [AVMetadata](arkts-apis-avsession-i.md#avmetadata10)) => void                    | Yes  | Callback used for subscription. The **data** parameter in the callback indicates the changed metadata.                        |
1420
1421**Error codes**
1422
1423For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1424
1425| ID| Error Message|
1426| -------- | ------------------------------ |
1427| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1428| 6600101  | Session service exception. |
1429| 6600103  | The session controller does not exist. |
1430
1431**Example**
1432
1433```ts
1434avsessionController.on('metadataChange', 'all', (metadata: avSession.AVMetadata) => {
1435  console.info(`on metadataChange assetId : ${metadata.assetId}`);
1436});
1437
1438avsessionController.on('metadataChange', ['assetId', 'title', 'description'], (metadata: avSession.AVMetadata) => {
1439  console.info(`on metadataChange assetId : ${metadata.assetId}`);
1440});
1441
1442```
1443
1444## off('metadataChange')<sup>10+</sup>
1445
1446off(type: 'metadataChange', callback?: (data: AVMetadata) => void)
1447
1448Unsubscribes from metadata change events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.
1449
1450**Atomic service API**: This API can be used in atomic services since API version 12.
1451
1452**System capability**: SystemCapability.Multimedia.AVSession.Core
1453
1454**Parameters**
1455
1456| Name  | Type                                              | Mandatory| Description                                                   |
1457| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------ |
1458| type     | string                                           | Yes  | Event type, which is **'metadataChange'** in this case.        |
1459| callback | (data: [AVMetadata](arkts-apis-avsession-i.md#avmetadata10)) => void        | No  | Callback used for subscription. The **data** parameter in the callback indicates the changed metadata.<br>The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.                        |
1460
1461**Error codes**
1462
1463For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1464
1465| ID| Error Message|
1466| -------- | ---------------- |
1467| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1468| 6600101  | Session service exception. |
1469| 6600103  | The session controller does not exist. |
1470
1471**Example**
1472
1473```ts
1474avsessionController.off('metadataChange');
1475```
1476
1477## on('playbackStateChange')<sup>10+</sup>
1478
1479on(type: 'playbackStateChange', filter: Array\<keyof AVPlaybackState> | 'all', callback: (state: AVPlaybackState) => void)
1480
1481Subscribes to playback state change events.
1482
1483Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.
1484
1485**Atomic service API**: This API can be used in atomic services since API version 12.
1486
1487**System capability**: SystemCapability.Multimedia.AVSession.Core
1488
1489**Parameters**
1490
1491| Name  | Type      | Mandatory| Description     |
1492| --------| -----------|-----|------------|
1493| type     | string    | Yes  | Event type. The event **'playbackStateChange'** is triggered when the playback state changes.|
1494| filter   | Array\<keyof&nbsp;[AVPlaybackState](arkts-apis-avsession-i.md#avplaybackstate10)\>&nbsp;&#124;&nbsp;'all' | Yes  | The value **'all'** indicates that any playback state field change will trigger the event, and **Array<keyof&nbsp;[AVPlaybackState](arkts-apis-avsession-i.md#avplaybackstate10)\>** indicates that only changes to the listed playback state field will trigger the event.|
1495| callback | (state: [AVPlaybackState](arkts-apis-avsession-i.md#avplaybackstate10)) => void       | Yes  | Callback used for subscription. The **state** parameter in the callback indicates the changed playback state.|
1496
1497**Error codes**
1498
1499For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1500
1501| ID| Error Message|
1502| -------- | ------------------------------ |
1503| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1504| 6600101  | Session service exception. |
1505| 6600103  | The session controller does not exist. |
1506
1507**Example**
1508
1509```ts
1510avsessionController.on('playbackStateChange', 'all', (playbackState: avSession.AVPlaybackState) => {
1511  console.info(`on playbackStateChange state : ${playbackState.state}`);
1512});
1513
1514avsessionController.on('playbackStateChange', ['state', 'speed', 'loopMode'], (playbackState: avSession.AVPlaybackState) => {
1515  console.info(`on playbackStateChange state : ${playbackState.state}`);
1516});
1517```
1518
1519## off('playbackStateChange')<sup>10+</sup>
1520
1521off(type: 'playbackStateChange', callback?: (state: AVPlaybackState) => void)
1522
1523Unsubscribes from playback state change events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.
1524
1525**Atomic service API**: This API can be used in atomic services since API version 12.
1526
1527**System capability**: SystemCapability.Multimedia.AVSession.Core
1528
1529**Parameters**
1530
1531| Name  | Type                                                        | Mandatory| Description                                                    |
1532| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
1533| type     | string                                                       | Yes  | Event type, which is **'playbackStateChange'** in this case.   |
1534| callback | (state: [AVPlaybackState](arkts-apis-avsession-i.md#avplaybackstate10)) => void         | No  | Callback function, where the **state** parameter indicates the new playback state.<br>The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.                     |
1535
1536**Error codes**
1537
1538For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1539
1540| ID| Error Message|
1541| -------- | ---------------- |
1542| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1543| 6600101  | Session service exception. |
1544| 6600103  | The session controller does not exist. |
1545
1546**Example**
1547
1548```ts
1549avsessionController.off('playbackStateChange');
1550```
1551
1552## on('callMetadataChange')<sup>11+</sup>
1553
1554on(type: 'callMetadataChange', filter: Array\<keyof CallMetadata> | 'all', callback: Callback\<CallMetadata>): void
1555
1556Subscribes to call metadata change events.
1557
1558Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.
1559
1560**Atomic service API**: This API can be used in atomic services since API version 12.
1561
1562**System capability**: SystemCapability.Multimedia.AVSession.Core
1563
1564**Parameters**
1565
1566| Name  | Type      | Mandatory| Description     |
1567| --------| -----------|-----|------------|
1568| type     | string    | Yes  | Event type. The event **'callMetadataChange'** is triggered when the call metadata changes.|
1569| filter   | Array\<keyof&nbsp;[CallMetadata](arkts-apis-avsession-i.md#callmetadata11)\>&nbsp;&#124;&nbsp;'all' | Yes  | The value **'all'** indicates that any call metadata field change will trigger the event, and **Array<keyof&nbsp;[CallMetadata](arkts-apis-avsession-i.md#callmetadata11)\>** indicates that only changes to the listed metadata field will trigger the event.|
1570| callback | Callback<[CallMetadata](arkts-apis-avsession-i.md#callmetadata11)\>   | Yes  | Callback used for subscription. The **callmetadata** parameter in the callback indicates the changed call metadata.|
1571
1572**Error codes**
1573
1574For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1575
1576| ID| Error Message|
1577| -------- | ------------------------------ |
1578| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1579| 6600101  | Session service exception. |
1580| 6600103  | The session controller does not exist. |
1581
1582**Example**
1583
1584```ts
1585avsessionController.on('callMetadataChange', 'all', (callmetadata: avSession.CallMetadata) => {
1586  console.info(`on callMetadataChange state : ${callmetadata.name}`);
1587});
1588
1589avsessionController.on('callMetadataChange', ['name'], (callmetadata: avSession.CallMetadata) => {
1590  console.info(`on callMetadataChange state : ${callmetadata.name}`);
1591});
1592```
1593
1594## off('callMetadataChange')<sup>11+</sup>
1595
1596off(type: 'callMetadataChange', callback?: Callback\<CallMetadata>): void
1597
1598Unsubscribes from call metadata change events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.
1599
1600**Atomic service API**: This API can be used in atomic services since API version 12.
1601
1602**System capability**: SystemCapability.Multimedia.AVSession.Core
1603
1604**Parameters**
1605
1606| Name  | Type                                                        | Mandatory| Description                                                    |
1607| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
1608| type     | string                                                       | Yes  | Event type, which is **'callMetadataChange'** in this case.   |
1609| callback | Callback<[CallMetadata](arkts-apis-avsession-i.md#callmetadata11)\>       | No  | Callback used for unsubscription. The **calldata** parameter in the callback indicates the changed call metadata.<br>The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.     |
1610
1611**Error codes**
1612
1613For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1614
1615| ID| Error Message|
1616| -------- | ---------------- |
1617| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1618| 6600101  | Session service exception. |
1619| 6600103  | The session controller does not exist. |
1620
1621**Example**
1622
1623```ts
1624avsessionController.off('callMetadataChange');
1625```
1626
1627## on('callStateChange')<sup>11+</sup>
1628
1629on(type: 'callStateChange', filter: Array\<keyof AVCallState> | 'all', callback: Callback\<AVCallState>): void
1630
1631Subscribes to call state change events.
1632
1633Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.
1634
1635**Atomic service API**: This API can be used in atomic services since API version 12.
1636
1637**System capability**: SystemCapability.Multimedia.AVSession.Core
1638
1639**Parameters**
1640
1641| Name  | Type      | Mandatory| Description     |
1642| --------| -----------|-----|------------|
1643| type     | string    | Yes  | Event type. The event **'callStateChange'** is triggered when the call state changes.|
1644| filter   | Array<keyof&nbsp;[AVCallState](arkts-apis-avsession-i.md#avcallstate11)\>&nbsp;&#124;&nbsp;'all' | Yes  | The value **'all'** indicates that any call state field change will trigger the event, and **Array<keyof&nbsp;[AVCallState](arkts-apis-avsession-i.md#avcallstate11)\>** indicates that only changes to the listed call state field will trigger the event.|
1645| callback | Callback<[AVCallState](arkts-apis-avsession-i.md#avcallstate11)\>       | Yes  | Callback function, where the **callstate** parameter indicates the new call state.|
1646
1647**Error codes**
1648
1649For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1650
1651| ID| Error Message|
1652| -------- | ------------------------------ |
1653| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1654| 6600101  | Session service exception. |
1655| 6600103  | The session controller does not exist. |
1656
1657**Example**
1658
1659```ts
1660avsessionController.on('callStateChange', 'all', (callstate: avSession.AVCallState) => {
1661  console.info(`on callStateChange state : ${callstate.state}`);
1662});
1663
1664avsessionController.on('callStateChange', ['state'], (callstate: avSession.AVCallState) => {
1665  console.info(`on callStateChange state : ${callstate.state}`);
1666});
1667```
1668
1669## off('callStateChange')<sup>11+</sup>
1670
1671off(type: 'callStateChange', callback?: Callback\<AVCallState>): void
1672
1673Unsubscribes from call state change events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.
1674
1675**Atomic service API**: This API can be used in atomic services since API version 12.
1676
1677**System capability**: SystemCapability.Multimedia.AVSession.Core
1678
1679**Parameters**
1680
1681| Name  | Type                                                        | Mandatory| Description                                                    |
1682| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
1683| type     | string                                                       | Yes  | Event type, which is **'callStateChange'** in this case.   |
1684| callback | Callback<[AVCallState](arkts-apis-avsession-i.md#avcallstate11)\>           | No  | Callback function, where the **callstate** parameter indicates the new call metadata.<br>The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.     |
1685
1686**Error codes**
1687
1688For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1689
1690| ID| Error Message|
1691| -------- | ---------------- |
1692| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1693| 6600101  | Session service exception. |
1694| 6600103  | The session controller does not exist. |
1695
1696**Example**
1697
1698```ts
1699avsessionController.off('callMetadataChange');
1700```
1701
1702## on('sessionDestroy')<sup>10+</sup>
1703
1704on(type: 'sessionDestroy', callback: () => void)
1705
1706Subscribes to session destruction events.
1707
1708Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.
1709
1710**Atomic service API**: This API can be used in atomic services since API version 12.
1711
1712**System capability**: SystemCapability.Multimedia.AVSession.Core
1713
1714**Parameters**
1715
1716| Name  | Type      | Mandatory| Description                                                        |
1717| -------- | ---------- | ---- | ------------------------------------------------------------ |
1718| type     | string     | Yes  | Event type. The event **'sessionDestroy'** is triggered when a session is destroyed.|
1719| callback | () => void | Yes  | Callback used for subscription. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object.                 |
1720
1721**Error codes**
1722
1723For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1724
1725| ID| Error Message|
1726| -------- | ------------------------------ |
1727| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1728| 6600101  | Session service exception. |
1729| 6600103  | The session controller does not exist. |
1730
1731**Example**
1732
1733```ts
1734avsessionController.on('sessionDestroy', () => {
1735  console.info('on sessionDestroy : SUCCESS ');
1736});
1737```
1738
1739## off('sessionDestroy')<sup>10+</sup>
1740
1741off(type: 'sessionDestroy', callback?: () => void)
1742
1743Unsubscribes from session destruction events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.
1744
1745**Atomic service API**: This API can be used in atomic services since API version 12.
1746
1747**System capability**: SystemCapability.Multimedia.AVSession.Core
1748
1749**Parameters**
1750
1751| Name  | Type      | Mandatory| Description                                                     |
1752| -------- | ---------- | ---- | ----------------------------------------------------- |
1753| type     | string     | Yes  | Event type, which is **'sessionDestroy'** in this case.        |
1754| 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.                                              |
1755
1756**Error codes**
1757
1758For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1759
1760| ID| Error Message|
1761| -------- | ---------------- |
1762| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1763| 6600101  | Session service exception. |
1764| 6600103  | The session controller does not exist. |
1765
1766**Example**
1767
1768```ts
1769avsessionController.off('sessionDestroy');
1770```
1771
1772## on('activeStateChange')<sup>10+</sup>
1773
1774on(type: 'activeStateChange', callback: (isActive: boolean) => void)
1775
1776Subscribes to session activation state change events.
1777
1778Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.
1779
1780**Atomic service API**: This API can be used in atomic services since API version 12.
1781
1782**System capability**: SystemCapability.Multimedia.AVSession.Core
1783
1784**Parameters**
1785
1786| Name  | Type                       | Mandatory| Description                                                        |
1787| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
1788| type     | string                      | Yes  | Event type. The event **'activeStateChange'** is triggered when the activation state of the session changes.|
1789| callback | (isActive: boolean) => void | Yes  | Callback used for subscription. The **isActive** parameter in the callback specifies whether the session is activated. The value **true** means that the service is activated, and **false** means the opposite.                  |
1790
1791**Error codes**
1792
1793For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1794
1795| ID| Error Message|
1796| -------- | ----------------------------- |
1797| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1798| 6600101  | Session service exception. |
1799| 6600103  |The session controller does not exist. |
1800
1801**Example**
1802
1803```ts
1804avsessionController.on('activeStateChange', (isActive: boolean) => {
1805  console.info(`on activeStateChange : SUCCESS : isActive ${isActive}`);
1806});
1807```
1808
1809## off('activeStateChange')<sup>10+</sup>
1810
1811off(type: 'activeStateChange', callback?: (isActive: boolean) => void)
1812
1813Unsubscribes from session activation state change events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.
1814
1815**Atomic service API**: This API can be used in atomic services since API version 12.
1816
1817**System capability**: SystemCapability.Multimedia.AVSession.Core
1818
1819**Parameters**
1820
1821| Name  | Type                       | Mandatory| Description                                                     |
1822| -------- | --------------------------- | ---- | ----------------------------------------------------- |
1823| type     | string                      | Yes  | Event type, which is **'activeStateChange'** in this case.     |
1824| callback | (isActive: boolean) => void | No  | Callback used for unsubscription. The **isActive** parameter in the callback specifies whether the session is activated. The value **true** means that the session is activated, and **false** means the opposite.<br>The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.                  |
1825
1826**Error codes**
1827
1828For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1829
1830| ID| Error Message|
1831| -------- | ---------------- |
1832| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1833| 6600101  | Session service exception. |
1834| 6600103  | The session controller does not exist. |
1835
1836**Example**
1837
1838```ts
1839avsessionController.off('activeStateChange');
1840```
1841
1842## on('validCommandChange')<sup>10+</sup>
1843
1844on(type: 'validCommandChange', callback: (commands: Array\<AVControlCommandType>) => void)
1845
1846Subscribes to valid command change events.
1847
1848Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.
1849
1850**Atomic service API**: This API can be used in atomic services since API version 12.
1851
1852**System capability**: SystemCapability.Multimedia.AVSession.Core
1853
1854**Parameters**
1855
1856| Name  | Type                                                        | Mandatory| Description                                                        |
1857| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
1858| type     | string                                                       | Yes  | Event type. The event **'validCommandChange'** is triggered when the valid commands supported by the session changes.|
1859| callback | (commands: Array<[AVControlCommandType](arkts-apis-avsession-t.md#avcontrolcommandtype10)\>) => void | Yes  | Callback used for subscription. The **commands** parameter in the callback is a set of valid commands.                    |
1860
1861**Error codes**
1862
1863For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1864
1865| ID| Error Message|
1866| -------- | ------------------------------ |
1867| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1868| 6600101  | Session service exception. |
1869| 6600103  | The session controller does not exist. |
1870
1871**Example**
1872
1873```ts
1874avsessionController.on('validCommandChange', (validCommands: avSession.AVControlCommandType[]) => {
1875  console.info(`validCommandChange : SUCCESS : size : ${validCommands.length}`);
1876  console.info(`validCommandChange : SUCCESS : validCommands : ${validCommands.values()}`);
1877});
1878```
1879
1880## off('validCommandChange')<sup>10+</sup>
1881
1882off(type: 'validCommandChange', callback?: (commands: Array\<AVControlCommandType>) => void)
1883
1884Unsubscribes from valid command change events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.
1885
1886**Atomic service API**: This API can be used in atomic services since API version 12.
1887
1888**System capability**: SystemCapability.Multimedia.AVSession.Core
1889
1890**Parameters**
1891
1892| Name  | Type                                                        | Mandatory| Description                                                       |
1893| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- |
1894| type     | string                                                       | Yes  | Event type, which is **'validCommandChange'** in this case.        |
1895| callback | (commands: Array<[AVControlCommandType](arkts-apis-avsession-t.md#avcontrolcommandtype10)\>) => void | No  | Callback used for unsubscription. The **commands** parameter in the callback is a set of valid commands.<br>The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.         |
1896
1897**Error codes**
1898
1899For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1900
1901| ID| Error Message          |
1902| -------- | ---------------- |
1903| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1904| 6600101  | Session service exception. |
1905| 6600103  | The session controller does not exist. |
1906
1907**Example**
1908
1909```ts
1910avsessionController.off('validCommandChange');
1911```
1912
1913## on('outputDeviceChange')<sup>10+</sup>
1914
1915on(type: 'outputDeviceChange', callback: (state: ConnectionState, device: OutputDeviceInfo) => void): void
1916
1917Subscribes to output device change events.
1918
1919Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.
1920
1921**Atomic service API**: This API can be used in atomic services since API version 12.
1922
1923**System capability**: SystemCapability.Multimedia.AVSession.Core
1924
1925**Parameters**
1926
1927| Name  | Type                                                   | Mandatory| Description                                                        |
1928| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
1929| type     | string                                                  | Yes  | Event type. The event **'outputDeviceChange'** is triggered when the output device changes.|
1930| callback | (state: [ConnectionState](arkts-apis-avsession-e.md#connectionstate10), device: [OutputDeviceInfo](arkts-apis-avsession-i.md#outputdeviceinfo10)) => void | Yes  | Callback used for subscription. The **device** parameter in the callback indicates the output device information.                        |
1931
1932**Error codes**
1933
1934For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1935
1936| ID| Error Message|
1937| -------- | ----------------------- |
1938| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1939| 6600101  | Session service exception. |
1940| 6600103  | The session controller does not exist. |
1941
1942**Example**
1943
1944```ts
1945avsessionController.on('outputDeviceChange', (state: avSession.ConnectionState, device: avSession.OutputDeviceInfo) => {
1946  console.info(`on outputDeviceChange state: ${state}, device : ${device}`);
1947});
1948```
1949
1950## off('outputDeviceChange')<sup>10+</sup>
1951
1952off(type: 'outputDeviceChange', callback?: (state: ConnectionState, device: OutputDeviceInfo) => void): void
1953
1954Unsubscribes from output device change events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.
1955
1956**Atomic service API**: This API can be used in atomic services since API version 12.
1957
1958**System capability**: SystemCapability.Multimedia.AVSession.Core
1959
1960**Parameters**
1961
1962| Name  | Type                                                   | Mandatory| Description                                                     |
1963| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------ |
1964| type     | string                                                  | Yes  | Event type, which is **'outputDeviceChange'** in this case.     |
1965| callback | (state: [ConnectionState](arkts-apis-avsession-e.md#connectionstate10), device: [OutputDeviceInfo](arkts-apis-avsession-i.md#outputdeviceinfo10)) => void | No  | Callback function, where the **device** parameter specifies the output device information.<br>The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.                        |
1966
1967**Error codes**
1968
1969For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
1970
1971| ID | Error Message         |
1972| -------- | ---------------- |
1973| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
1974| 6600101  | Session service exception. |
1975| 6600103  | The session controller does not exist. |
1976
1977**Example**
1978
1979```ts
1980avsessionController.off('outputDeviceChange');
1981```
1982
1983## on('sessionEvent')<sup>10+</sup>
1984
1985on(type: 'sessionEvent', callback: (sessionEvent: string, args: {[key: string]: Object}) => void): void
1986
1987Subscribes to session event change events. This API is called by the controller.
1988
1989Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.
1990
1991**Atomic service API**: This API can be used in atomic services since API version 12.
1992
1993**System capability**: SystemCapability.Multimedia.AVSession.Core
1994
1995**Parameters**
1996
1997| Name  | Type                                                        | Mandatory| Description                                                        |
1998| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
1999| type     | string                                                       | Yes  | Event type. The event **'sessionEvent'** is triggered when the session event changes.|
2000| callback | (sessionEvent: string, args: {[key: string]: Object}) => void         | Yes  | Callback used for subscription. **sessionEvent** in the callback indicates the name of the session event that changes, and **args** indicates the parameters carried in the event.         |
2001
2002**Error codes**
2003
2004For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2005
2006| ID| Error Message|
2007| -------- | ------------------------------ |
2008| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
2009| 6600101  | Session service exception. |
2010| 6600103  | The session controller does not exist. |
2011
2012**Example**
2013
2014```ts
2015import { BusinessError } from '@kit.BasicServicesKit';
2016import { avSession } from '@kit.AVSessionKit';
2017
2018let tag: string = "createNewSession";
2019let sessionId: string = "";
2020let controller:avSession.AVSessionController | undefined = undefined;
2021avSession.createAVSession(context, tag, "audio").then(async (data:avSession.AVSession)=> {
2022  currentAVSession = data;
2023  sessionId = currentAVSession.sessionId;
2024  controller = await currentAVSession.getController();
2025  console.info('CreateAVSession : SUCCESS :sessionid = ${sessionid}');
2026}).catch((err: BusinessError) => {
2027  console.error('CreateAVSession BusinessError:code: ${err.code}, message: ${err.message}')
2028});
2029if (controller !== undefined) {
2030  (controller as avSession.AVSessionController).on('sessionEvent', (sessionEvent, args) => {
2031    console.info(`OnSessionEvent, sessionEvent is ${sessionEvent}, args: ${JSON.stringify(args)}`);
2032  });
2033}
2034```
2035
2036## off('sessionEvent')<sup>10+</sup>
2037
2038off(type: 'sessionEvent', callback?: (sessionEvent: string, args: {[key: string]: Object}) => void): void
2039
2040Unsubscribes from session events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.
2041
2042**Atomic service API**: This API can be used in atomic services since API version 12.
2043
2044**System capability**: SystemCapability.Multimedia.AVSession.Core
2045
2046**Parameters**
2047
2048| Name  | Type                                                        | Mandatory| Description                                                    |
2049| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
2050| type     | string                                                       | Yes  | Event type, which is **'sessionEvent'** in this case.   |
2051| callback | (sessionEvent: string, args: {[key: string]: Object}) => void         | No  | Callback used for unsubscription. **sessionEvent** in the callback indicates the name of the session event that changes, and **args** indicates the parameters carried in the event.<br>The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.                     |
2052
2053**Error codes**
2054
2055For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2056
2057| ID| Error Message|
2058| -------- | ---------------- |
2059| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
2060| 6600101  | Session service exception. |
2061| 6600103  | The session controller does not exist. |
2062
2063**Example**
2064
2065```ts
2066avsessionController.off('sessionEvent');
2067```
2068
2069## on('queueItemsChange')<sup>10+</sup>
2070
2071on(type: 'queueItemsChange', callback: (items: Array<[AVQueueItem](arkts-apis-avsession-i.md#avqueueitem10)\>) => void): void
2072
2073Subscribes to playlist item change events. This API is called by the controller.
2074
2075Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.
2076
2077**Atomic service API**: This API can be used in atomic services since API version 12.
2078
2079**System capability**: SystemCapability.Multimedia.AVSession.Core
2080
2081**Parameters**
2082
2083| Name  | Type                                                  | Mandatory| Description                                                                        |
2084| -------- | ----------------------------------------------------- | ---- | ---------------------------------------------------------------------------- |
2085| type     | string                                                | Yes  | Event type. The event **'queueItemsChange'** is triggered when one or more items in the playlist changes.|
2086| callback | (items: Array<[AVQueueItem](arkts-apis-avsession-i.md#avqueueitem10)\>) => void  | Yes  | Callback used for subscription. The **items** parameter in the callback indicates the changed items in the playlist.                           |
2087
2088**Error codes**
2089
2090For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2091
2092| ID| Error Message|
2093| -------- | ------------------------------ |
2094| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
2095| 6600101  | Session service exception. |
2096| 6600103  | The session controller does not exist. |
2097
2098**Example**
2099
2100```ts
2101avsessionController.on('queueItemsChange', (items: avSession.AVQueueItem[]) => {
2102  console.info(`OnQueueItemsChange, items length is ${items.length}`);
2103});
2104```
2105
2106## off('queueItemsChange')<sup>10+</sup>
2107
2108off(type: 'queueItemsChange', callback?: (items: Array<[AVQueueItem](arkts-apis-avsession-i.md#avqueueitem10)\>) => void): void
2109
2110Unsubscribes from playback item change events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.
2111
2112**Atomic service API**: This API can be used in atomic services since API version 12.
2113
2114**System capability**: SystemCapability.Multimedia.AVSession.Core
2115
2116**Parameters**
2117
2118| Name   | Type                                                | Mandatory| Description                                                                                               |
2119| -------- | ---------------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------- |
2120| type     | string                                               | Yes  | Event type, which is **'queueItemsChange'** in this case.                                                    |
2121| callback | (items: Array<[AVQueueItem](arkts-apis-avsession-i.md#avqueueitem10)\>) => void | No  | Callback used for unsubscription. The **items** parameter in the callback indicates the changed items in the playlist.<br>The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.|
2122
2123**Error codes**
2124
2125For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2126
2127| ID| Error Message|
2128| -------- | ---------------- |
2129| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
2130| 6600101  | Session service exception. |
2131| 6600103  | The session controller does not exist. |
2132
2133**Example**
2134
2135```ts
2136avsessionController.off('queueItemsChange');
2137```
2138
2139## on('queueTitleChange')<sup>10+</sup>
2140
2141on(type: 'queueTitleChange', callback: (title: string) => void): void
2142
2143Subscribes to playlist name change events. This API is called by the controller.
2144
2145**Atomic service API**: This API can be used in atomic services since API version 12.
2146
2147**System capability**: SystemCapability.Multimedia.AVSession.Core
2148
2149**Parameters**
2150
2151| Name  | Type                    | Mandatory| Description                                                                            |
2152| -------- | ----------------------- | ---- | ------------------------------------------------------------------------------- |
2153| type     | string                  | Yes  | Event type. The event **'queueTitleChange'** is triggered when the playlist name changes.|
2154| callback | (title: string) => void | Yes  | Callback used for subscription. The **title** parameter in the callback indicates the changed playlist name.                               |
2155
2156**Error codes**
2157
2158For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2159
2160| ID| Error Message|
2161| -------- | ------------------------------ |
2162| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
2163| 6600101  | Session service exception. |
2164| 6600103  | The session controller does not exist. |
2165
2166**Example**
2167
2168```ts
2169avsessionController.on('queueTitleChange', (title: string) => {
2170  console.info(`queueTitleChange, title is ${title}`);
2171});
2172```
2173
2174## off('queueTitleChange')<sup>10+</sup>
2175
2176off(type: 'queueTitleChange', callback?: (title: string) => void): void
2177
2178Unsubscribes from playlist name change events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.
2179
2180**Atomic service API**: This API can be used in atomic services since API version 12.
2181
2182**System capability**: SystemCapability.Multimedia.AVSession.Core
2183
2184**Parameters**
2185
2186| Name   | Type                   | Mandatory| Description                                                                                                   |
2187| -------- | ----------------------- | ---- | ------------------------------------------------------------------------------------------------------- |
2188| type     | string                  | Yes  | Event type, which is **'queueTitleChange'** in this case.                                                        |
2189| callback | (title: string) => void | No  | Callback used for unsubscription. The **items** parameter in the callback indicates the changed playlist name.<br>The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.|
2190
2191**Error codes**
2192
2193For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2194
2195| ID| Error Message|
2196| -------- | ---------------- |
2197| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
2198| 6600101  | Session service exception. |
2199| 6600103  | The session controller does not exist. |
2200
2201**Example**
2202
2203```ts
2204avsessionController.off('queueTitleChange');
2205```
2206
2207## on('extrasChange')<sup>10+</sup>
2208
2209on(type: 'extrasChange', callback: (extras: {[key: string]: Object}) => void): void
2210
2211Subscribes to custom media packet change events. This API is called by the controller.
2212
2213**Atomic service API**: This API can be used in atomic services since API version 12.
2214
2215**System capability**: SystemCapability.Multimedia.AVSession.Core
2216
2217**Parameters**
2218
2219| Name  | Type                                                        | Mandatory| Description                                                        |
2220| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
2221| type     | string                                                       | Yes  | Event type. The event **'extrasChange'** is triggered when the provider sets a custom media packet.|
2222| callback | (extras: {[key: string]: Object}) => void         | Yes  | Callback used for subscription. The **extras** parameter in the callback indicates the custom media packet set by the provider. This packet is the same as that set in **dispatchSessionEvent**.         |
2223
2224**Error codes**
2225
2226For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2227
2228| ID| Error Message|
2229| -------- | ------------------------------ |
2230| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
2231| 6600101  | Session service exception. |
2232| 6600103  | The session controller does not exist. |
2233
2234**Example**
2235
2236```ts
2237import { BusinessError } from '@kit.BasicServicesKit';
2238import { avSession } from '@kit.AVSessionKit';
2239
2240let tag: string = "createNewSession";
2241let sessionId: string = "";
2242let controller:avSession.AVSessionController | undefined = undefined;
2243avSession.createAVSession(context, tag, "audio").then(async (data:avSession.AVSession)=> {
2244  currentAVSession = data;
2245  sessionId = currentAVSession.sessionId;
2246  controller = await currentAVSession.getController();
2247  console.info('CreateAVSession : SUCCESS :sessionid = ${sessionid}');
2248}).catch((err: BusinessError) => {
2249  console.error('CreateAVSession BusinessError:code: ${err.code}, message: ${err.message}')
2250});
2251if (controller !== undefined) {
2252  (controller as avSession.AVSessionController).on('extrasChange', (extras) => {
2253    console.info(`Caught extrasChange event,the new extra is: ${JSON.stringify(extras)}`);
2254  });
2255}
2256```
2257
2258## off('extrasChange')<sup>10+</sup>
2259
2260off(type: 'extrasChange', callback?: (extras: {[key: string]: Object}) => void): void
2261
2262Unsubscribes from custom media packet change events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.
2263
2264**Atomic service API**: This API can be used in atomic services since API version 12.
2265
2266**System capability**: SystemCapability.Multimedia.AVSession.Core
2267
2268**Parameters**
2269
2270| Name   | Type                   | Mandatory| Description                                                                                                   |
2271| -------- | ----------------------- | ---- | ------------------------------------------------------------------------------------------------------- |
2272| type     | string                  | Yes  | Event type, which is **'extrasChange'** in this case.                                                        |
2273| callback | (extras: {[key: string]: Object}) => void | No  | Callback used for unsubscription.<br>The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.|
2274
2275**Error codes**
2276
2277For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2278
2279| ID| Error Message|
2280| -------- | ----------------                       |
2281| 401 |  parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. |
2282| 6600101  | Session service exception. |
2283| 6600103  | The session controller does not exist. |
2284
2285**Example**
2286
2287```ts
2288avsessionController.off('extrasChange');
2289```
2290
2291## on('customDataChange')<sup>20+</sup>
2292
2293on(type: 'customDataChange', callback: Callback\<Record\<string, Object>>): void
2294
2295Subscribes to events indicating that custom data is sent to a remote device.
2296
2297**Atomic service API**: This API can be used in atomic services since API version 20.
2298
2299**System capability**: SystemCapability.Multimedia.AVSession.AVCast
2300
2301**Parameters**
2302
2303| Name  | Type                              | Mandatory| Description                                                        |
2304| -------- | ---------------------------------- | ---- | ------------------------------------------------------------ |
2305| type     | string                             | Yes  | Event type. The event **'customDataChange'** is triggered when the provider sends custom data.|
2306| callback | Callback\<Record\<string, Object>> | Yes  | Callback used to receive the custom data.                              |
2307
2308**Error codes**
2309
2310For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2311
2312| ID| Error Message                                                    |
2313| -------- | ------------------------------------------------------------ |
2314| 6600101  | Session service exception. |
2315| 6600103  | The session controller does not exist.                       |
2316
2317**Example**
2318
2319```ts
2320import { BusinessError } from '@kit.BasicServicesKit';
2321import { avSession } from '@kit.AVSessionKit';
2322
2323let tag: string = "createNewSession";
2324let sessionId: string = "";
2325let controller:avSession.AVSessionController | undefined = undefined;
2326avSession.createAVSession(context, tag, "audio").then(async (data:avSession.AVSession)=> {
2327  currentAVSession = data;
2328  sessionId = currentAVSession.sessionId;
2329  controller = await currentAVSession.getController();
2330  console.info('CreateAVSession : SUCCESS :sessionid = ${sessionid}');
2331}).catch((err: BusinessError) => {
2332  console.error('CreateAVSession BusinessError:code: ${err.code}, message: ${err.message}')
2333});
2334if (controller !== undefined) {
2335  (controller as avSession.AVSessionController).on('customDataChange', (callback) => {
2336    console.info(`Caught customDataChange event,the new callback is: ${JSON.stringify(callback)}`);
2337  });
2338}
2339```
2340
2341## off('customDataChange')<sup>20+</sup>
2342
2343off(type: 'customDataChange', callback?: Callback\<Record\<string, Object>>): void
2344
2345Unsubscribes from events indicating that custom data is sent to a remote device.
2346
2347**Atomic service API**: This API can be used in atomic services since API version 20.
2348
2349**System capability**: SystemCapability.Multimedia.AVSession.AVCast
2350
2351**Parameters**
2352
2353| Name  | Type                              | Mandatory| Description                                                        |
2354| -------- | ---------------------------------- | ---- | ------------------------------------------------------------ |
2355| type     | string                             | Yes  | Event type, which is **'customDataChange'** in this case.        |
2356| callback | Callback\<Record\<string, Object>> | No  | Callback used for unsubscription. The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.|
2357
2358**Error codes**
2359
2360For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2361
2362| ID| Error Message                                                    |
2363| -------- | ------------------------------------------------------------ |
2364| 6600101  | Session service exception. |
2365| 6600103  | The session controller does not exist.                       |
2366
2367**Example**
2368
2369```ts
2370avsessionController.off('customDataChange');
2371```
2372
2373## getAVPlaybackStateSync<sup>10+</sup>
2374
2375getAVPlaybackStateSync(): AVPlaybackState;
2376
2377Obtains the playback state of this session. This API returns the result synchronously.
2378
2379**Atomic service API**: This API can be used in atomic services since API version 12.
2380
2381**System capability**: SystemCapability.Multimedia.AVSession.Core
2382
2383**Return value**
2384
2385| Type                                                       | Description                                                        |
2386| --------- | ------------------------------------------------------------ |
2387| [AVPlaybackState](arkts-apis-avsession-i.md#avplaybackstate10)  | Playback state of the session.|
2388
2389**Error codes**
2390
2391For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2392
2393| ID| Error Message|
2394| -------- | ---------------------------------------- |
2395| 6600101  | Session service exception. |
2396| 6600102  | The session does not exist. |
2397| 6600103  | The session controller does not exist. |
2398
2399**Example**
2400
2401```ts
2402import { BusinessError } from '@kit.BasicServicesKit';
2403
2404try {
2405  let playbackState: avSession.AVPlaybackState = avsessionController.getAVPlaybackStateSync();
2406} catch (err) {
2407  let error = err as BusinessError;
2408  console.error(`getAVPlaybackStateSync error, error code: ${error.code}, error message: ${error.message}`);
2409}
2410```
2411
2412## getAVMetadataSync<sup>10+</sup>
2413
2414getAVMetadataSync(): AVMetadata
2415
2416Obtains the session metadata. This API returns the result synchronously.
2417
2418**Atomic service API**: This API can be used in atomic services since API version 12.
2419
2420**System capability**: SystemCapability.Multimedia.AVSession.Core
2421
2422**Return value**
2423
2424| Type                               | Description                         |
2425| ----------------------------------- | ----------------------------- |
2426| [AVMetadata](arkts-apis-avsession-i.md#avmetadata10) | Session metadata.|
2427
2428**Error codes**
2429
2430For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2431
2432| ID| Error Message|
2433| -------- | ---------------------------------------- |
2434| 6600101  | Session service exception. |
2435| 6600102  | The session does not exist. |
2436| 6600103  | The session controller does not exist. |
2437
2438**Example**
2439```ts
2440import { BusinessError } from '@kit.BasicServicesKit';
2441
2442try {
2443  let metaData: avSession.AVMetadata = avsessionController.getAVMetadataSync();
2444} catch (err) {
2445  let error = err as BusinessError;
2446  console.error(`getAVMetadataSync error, error code: ${error.code}, error message: ${error.message}`);
2447}
2448```
2449
2450## getAVCallState<sup>11+</sup>
2451
2452getAVCallState(): Promise\<AVCallState>
2453
2454Obtains the call state. This API uses a promise to return the result.
2455
2456**System capability**: SystemCapability.Multimedia.AVSession.Core
2457
2458**Return value**
2459
2460| Type                               | Description                         |
2461| ----------------------------------- | ----------------------------- |
2462| Promise<[AVCallState](arkts-apis-avsession-i.md#avcallstate11)\> | Promise used to return the call state obtained.|
2463
2464**Error codes**
2465
2466For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2467
2468| ID| Error Message|
2469| -------- | ---------------------------------------- |
2470| 6600101  | Session service exception. |
2471| 6600102  | The session does not exist. |
2472| 6600103  | The session controller does not exist. |
2473
2474**Example**
2475
2476```ts
2477import { BusinessError } from '@kit.BasicServicesKit';
2478
2479avsessionController.getAVCallState().then((callstate: avSession.AVCallState) => {
2480  console.info(`getAVCallState : SUCCESS : state : ${callstate.state}`);
2481}).catch((err: BusinessError) => {
2482  console.error(`getAVCallState BusinessError: code: ${err.code}, message: ${err.message}`);
2483});
2484```
2485
2486## getAVCallState<sup>11+</sup>
2487
2488getAVCallState(callback: AsyncCallback\<AVCallState>): void
2489
2490Obtains the call state. This API uses an asynchronous callback to return the result.
2491
2492**System capability**: SystemCapability.Multimedia.AVSession.Core
2493
2494**Parameters**
2495
2496| Name  | Type                                     | Mandatory| Description                      |
2497| -------- | ----------------------------------------- | ---- | -------------------------- |
2498| callback | AsyncCallback<[AVCallState](arkts-apis-avsession-i.md#avcallstate11)\> | Yes  | Callback used to return the call state obtained.|
2499
2500**Error codes**
2501
2502For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2503
2504| ID| Error Message|
2505| -------- | ---------------------------------------- |
2506| 6600101  | Session service exception. |
2507| 6600102  | The session does not exist. |
2508| 6600103  | The session controller does not exist. |
2509
2510**Example**
2511
2512```ts
2513import { BusinessError } from '@kit.BasicServicesKit';
2514
2515avsessionController.getAVCallState((err: BusinessError, callstate: avSession.AVCallState) => {
2516  if (err) {
2517    console.error(`getAVCallState BusinessError: code: ${err.code}, message: ${err.message}`);
2518  } else {
2519    console.info(`getAVCallState : SUCCESS : state : ${callstate.state}`);
2520  }
2521});
2522```
2523
2524## getCallMetadata<sup>11+</sup>
2525
2526getCallMetadata(): Promise\<CallMetadata>
2527
2528Obtains the call metadata. This API uses a promise to return the result.
2529
2530**System capability**: SystemCapability.Multimedia.AVSession.Core
2531
2532**Return value**
2533
2534| Type                               | Description                         |
2535| ----------------------------------- | ----------------------------- |
2536| Promise<[CallMetadata](arkts-apis-avsession-i.md#callmetadata11)\> | Promise used to return the metadata obtained.|
2537
2538**Error codes**
2539
2540For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2541
2542| ID| Error Message|
2543| -------- | ---------------------------------------- |
2544| 6600101  | Session service exception. |
2545| 6600102  | The session does not exist. |
2546| 6600103  | The session controller does not exist. |
2547
2548**Example**
2549
2550```ts
2551import { BusinessError } from '@kit.BasicServicesKit';
2552
2553avsessionController.getCallMetadata().then((calldata: avSession.CallMetadata) => {
2554  console.info(`getCallMetadata : SUCCESS : name : ${calldata.name}`);
2555}).catch((err: BusinessError) => {
2556  console.error(`getCallMetadata BusinessError: code: ${err.code}, message: ${err.message}`);
2557});
2558```
2559
2560## getCallMetadata<sup>11+</sup>
2561
2562getCallMetadata(callback: AsyncCallback\<CallMetadata>): void
2563
2564Obtains the call metadata. This API uses an asynchronous callback to return the result.
2565
2566**System capability**: SystemCapability.Multimedia.AVSession.Core
2567
2568**Parameters**
2569
2570| Name  | Type                                     | Mandatory| Description                      |
2571| -------- | ----------------------------------------- | ---- | -------------------------- |
2572| callback | AsyncCallback<[CallMetadata](arkts-apis-avsession-i.md#callmetadata11)\> | Yes  | Callback used to return the metadata obtained.|
2573
2574**Error codes**
2575
2576For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2577
2578| ID| Error Message|
2579| -------- | ---------------------------------------- |
2580| 6600101  | Session service exception. |
2581| 6600102  | The session does not exist. |
2582| 6600103  | The session controller does not exist. |
2583
2584**Example**
2585
2586```ts
2587import { BusinessError } from '@kit.BasicServicesKit';
2588
2589avsessionController.getCallMetadata((err: BusinessError, calldata: avSession.CallMetadata) => {
2590  if (err) {
2591    console.error(`getCallMetadata BusinessError: code: ${err.code}, message: ${err.message}`);
2592  } else {
2593    console.info(`getCallMetadata : SUCCESS : name : ${calldata.name}`);
2594  }
2595});
2596```
2597
2598## getAVQueueTitleSync<sup>10+</sup>
2599
2600getAVQueueTitleSync(): string
2601
2602Obtains the name of the playlist of this session. This API returns the result synchronously.
2603
2604**Atomic service API**: This API can be used in atomic services since API version 12.
2605
2606**System capability**: SystemCapability.Multimedia.AVSession.Core
2607
2608**Return value**
2609
2610| Type            | Description                          |
2611| ---------------- | ----------------------------- |
2612| string | Playlist name.|
2613
2614**Error codes**
2615
2616For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2617
2618| ID| Error Message|
2619| -------- | ---------------------------------------- |
2620| 6600101  | Session service exception. |
2621| 6600102  | The session does not exist. |
2622| 6600103  | The session controller does not exist. |
2623
2624**Example**
2625
2626```ts
2627import { BusinessError } from '@kit.BasicServicesKit';
2628
2629try {
2630  let currentQueueTitle: string = avsessionController.getAVQueueTitleSync();
2631} catch (err) {
2632  let error = err as BusinessError;
2633  console.error(`getAVQueueTitleSync error, error code: ${error.code}, error message: ${error.message}`);
2634}
2635```
2636
2637## getAVQueueItemsSync<sup>10+</sup>
2638
2639getAVQueueItemsSync(): Array\<AVQueueItem\>
2640
2641Obtains the information related to the items in the playlist of this session. This API returns the result synchronously.
2642
2643**Atomic service API**: This API can be used in atomic services since API version 12.
2644
2645**System capability**: SystemCapability.Multimedia.AVSession.Core
2646
2647**Return value**
2648
2649| Type                                         | Description                          |
2650| --------------------------------------------- | ----------------------------- |
2651| Array<[AVQueueItem](arkts-apis-avsession-i.md#avqueueitem10)\> | Items in the queue.|
2652
2653**Error codes**
2654
2655For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2656
2657| ID| Error Message|
2658| -------- | ---------------------------------------- |
2659| 6600101  | Session service exception. |
2660| 6600102  | The session does not exist. |
2661| 6600103  | The session controller does not exist. |
2662
2663**Example**
2664
2665```ts
2666import { BusinessError } from '@kit.BasicServicesKit';
2667
2668try {
2669  let currentQueueItems: Array<avSession.AVQueueItem> = avsessionController.getAVQueueItemsSync();
2670} catch (err) {
2671  let error = err as BusinessError;
2672  console.error(`getAVQueueItemsSync error, error code: ${error.code}, error message: ${error.message}`);
2673}
2674```
2675
2676## getOutputDeviceSync<sup>10+</sup>
2677
2678getOutputDeviceSync(): OutputDeviceInfo
2679
2680Obtains the output device information. This API returns the result synchronously.
2681
2682**Atomic service API**: This API can be used in atomic services since API version 12.
2683
2684**System capability**: SystemCapability.Multimedia.AVSession.Core
2685
2686**Return value**
2687
2688| Type                                           | Description                             |
2689| ----------------------------------------------- | --------------------------------- |
2690| [OutputDeviceInfo](arkts-apis-avsession-i.md#outputdeviceinfo10) | Information about the output device.|
2691
2692**Error codes**
2693
2694For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2695
2696| ID| Error Message|
2697| -------- | ---------------------------------------- |
2698| 6600101  | Session service exception. |
2699| 6600103  | The session controller does not exist. |
2700
2701**Example**
2702
2703```ts
2704import { BusinessError } from '@kit.BasicServicesKit';
2705
2706try {
2707  let currentOutputDevice: avSession.OutputDeviceInfo = avsessionController.getOutputDeviceSync();
2708} catch (err) {
2709  let error = err as BusinessError;
2710  console.error(`getOutputDeviceSync error, error code: ${error.code}, error message: ${error.message}`);
2711}
2712```
2713
2714## isActiveSync<sup>10+</sup>
2715
2716isActiveSync(): boolean
2717
2718Checks whether the session is activated. This API returns the result synchronously.
2719
2720**Atomic service API**: This API can be used in atomic services since API version 12.
2721
2722**System capability**: SystemCapability.Multimedia.AVSession.Core
2723
2724**Return value**
2725
2726| Type             | Description                                                        |
2727| ----------------- | ------------------------------------------------------------ |
2728| boolean | Returns **true** is returned if the session is activated; returns **false** otherwise.|
2729
2730**Error codes**
2731
2732For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2733
2734| ID| Error Message|
2735| -------- | ---------------------------------------- |
2736| 6600101  | Session service exception. |
2737| 6600102  | The session does not exist. |
2738| 6600103  | The session controller does not exist. |
2739
2740**Example**
2741
2742```ts
2743import { BusinessError } from '@kit.BasicServicesKit';
2744
2745try {
2746  let isActive: boolean = avsessionController.isActiveSync();
2747} catch (err) {
2748  let error = err as BusinessError;
2749  console.error(`isActiveSync error, error code: ${error.code}, error message: ${error.message}`);
2750}
2751```
2752
2753## getValidCommandsSync<sup>10+</sup>
2754
2755getValidCommandsSync(): Array\<AVControlCommandType\>
2756
2757Obtains valid commands supported by the session. This API returns the result synchronously.
2758
2759**Atomic service API**: This API can be used in atomic services since API version 12.
2760
2761**System capability**: SystemCapability.Multimedia.AVSession.Core
2762
2763**Return value**
2764
2765| Type                                                        | Description                             |
2766| ------------------------------------------------------------ | --------------------------------- |
2767| Array<[AVControlCommandType](arkts-apis-avsession-t.md#avcontrolcommandtype10)\> | A set of valid commands.|
2768
2769**Error codes**
2770
2771For details about the error codes, see [AVSession Management Error Codes](errorcode-avsession.md).
2772
2773| ID| Error Message|
2774| -------- | ---------------------------------------- |
2775| 6600101  | Session service exception. |
2776| 6600102  | The session does not exist. |
2777| 6600103  | The session controller does not exist. |
2778
2779**Example**
2780
2781```ts
2782import { BusinessError } from '@kit.BasicServicesKit';
2783
2784try {
2785  let validCommands: Array<avSession.AVControlCommandType> = avsessionController.getValidCommandsSync();
2786} catch (err) {
2787  let error = err as BusinessError;
2788  console.error(`getValidCommandsSync error, error code: ${error.code}, error message: ${error.message}`);
2789}
2790```
2791