# @ohos.multimedia.avsession (AVSession Management)
The **avSession** module provides APIs for media playback control so that applications can access the system's Media Controller.
This module provides the following typical features related to media sessions:
- [AVSession](#avsession10): used to set session metadata, playback state information, and more.
- [AVSessionController](#avsessioncontroller10): used to obtain session IDs, send commands and events to sessions, and obtain the session metadata and playback state information.
- [AVCastController](#avcastcontroller10): used to control playback, listen for remote playback state changes, and obtain the remote playback state in casting scenarios.
> **NOTE**
>
> 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.
## Modules to Import
```js
import avSession from '@ohos.multimedia.avsession';
```
## avSession.createAVSession10+
createAVSession(context: Context, tag: string, type: AVSessionType): Promise\
Creates a media session. This API uses a promise to return the result. An ability can have only one session, and repeated calling of this API fails.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------------- | ---- | ------------------------------ |
| context| [Context](js-apis-inner-app-context.md) | Yes| Application context, which provides application environment information.|
| tag | string | Yes | Custom session name. |
| type | [AVSessionType](#avsessiontype10) | Yes | Session type, which can be audio or video.|
**Return value**
| Type | Description |
| --------------------------------- | ------------------------------------------------------------ |
| Promise<[AVSession](#avsession10)\> | Promise used to return the media session obtained, which can be used to obtain the session ID, set the metadata and playback state information, and send key events.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
let currentAVSession;
let tag = "createNewSession";
let context = featureAbility.getContext();
let sessionId; // Used as an input parameter of subsequent functions.
avSession.createAVSession(context, tag, "audio").then((data) => {
currentAVSession = data;
sessionId = currentAVSession.sessionId;
console.info(`CreateAVSession : SUCCESS : sessionId = ${sessionId}`);
}).catch((err) => {
console.info(`CreateAVSession BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## avSession.createAVSession10+
createAVSession(context: Context, tag: string, type: AVSessionType, callback: AsyncCallback\): void
Creates a media session. This API uses an asynchronous callback to return the result. An ability can have only one session, and repeated calling of this API fails.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
| context| [Context](js-apis-inner-app-context.md) | Yes| Application context, which provides application environment information. |
| tag | string | Yes | Custom session name. |
| type | [AVSessionType](#avsessiontype10) | Yes | Session type, which can be audio or video. |
| callback | AsyncCallback<[AVSession](#avsession10)\> | Yes | Callback used to return the media session obtained, which can be used to obtain the session ID, set the metadata and playback state information, and send key events.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
let currentAVSession;
let tag = "createNewSession";
let context = featureAbility.getContext();
let sessionId; // Used as an input parameter of subsequent functions.
avSession.createAVSession(context, tag, "audio", function (err, data) {
if (err) {
console.info(`CreateAVSession BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
currentAVSession = data;
sessionId = currentAVSession.sessionId;
console.info(`CreateAVSession : SUCCESS : sessionId = ${sessionId}`);
}
});
```
## avSession.getAllSessionDescriptors
getAllSessionDescriptors(): Promise\>>
Obtains the descriptors of all sessions. This API uses a promise to return the result.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Return value**
| Type | Description |
| ------------------------------------------------------------ | --------------------------------------------- |
| Promise\\>\> | Promise used to return an array of **AVSessionDescriptor** objects, each of which is read only.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
avSession.getAllSessionDescriptors().then((descriptors) => {
console.info(`getAllSessionDescriptors : SUCCESS : descriptors.length : ${descriptors.length}`);
if(descriptors.length > 0 ){
console.info(`getAllSessionDescriptors : SUCCESS : descriptors[0].isActive : ${descriptors[0].isActive}`);
console.info(`GetAllSessionDescriptors : SUCCESS : descriptors[0].type : ${descriptors[0].type}`);
console.info(`GetAllSessionDescriptors : SUCCESS : descriptors[0].sessionTag : ${descriptors[0].sessionTag}`);
}
}).catch((err) => {
console.error(`GetAllSessionDescriptors BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## avSession.getAllSessionDescriptors
getAllSessionDescriptors(callback: AsyncCallback\>>): void
Obtains the descriptors of all sessions. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ |
| callback | AsyncCallback\>\> | Yes | Callback used to return an array of **AVSessionDescriptor** objects, each of which is read only.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 |Session service exception. |
**Example**
```js
avSession.getAllSessionDescriptors(function (err, descriptors) {
if (err) {
console.error(`GetAllSessionDescriptors BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`GetAllSessionDescriptors : SUCCESS : descriptors.length : ${descriptors.length}`);
if(descriptors.length > 0 ){
console.info(`getAllSessionDescriptors : SUCCESS : descriptors[0].isActive : ${descriptors[0].isActive}`);
console.info(`getAllSessionDescriptors : SUCCESS : descriptors[0].type : ${descriptors[0].type}`);
console.info(`getAllSessionDescriptors : SUCCESS : descriptors[0].sessionTag : ${descriptors[0].sessionTag}`);
}
}
});
```
## avSession.getHistoricalSessionDescriptors10+
getHistoricalSessionDescriptors(maxSize?: number): Promise\>>
Obtains the descriptors of all sessions. This API uses a promise to return the result.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------ | ---- | -----------------------------------------------------------------|
| maxSize | number | No | Maximum number of descriptors to obtain. The value ranges from 0 to 10. If this parameter is left blank, the default value **3** is used.|
**Return value**
| Type | Description |
| --------------------------------------------------------------------------- | -------------------------------------- |
| Promise\\>\> | Promise used to return an array of **AVSessionDescriptor** objects, each of which is read only.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
avSession.getHistoricalSessionDescriptors().then((descriptors) => {
console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors.length : ${descriptors.length}`);
if(descriptors.length > 0 ){
console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].isActive : ${descriptors[0].isActive}`);
console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].type : ${descriptors[0].type}`);
console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].sessionTag : ${descriptors[0].sessionTag}`);
console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].sessionId : ${descriptors[0].sessionId}`);
console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].elementName.bundleName : ${descriptors[0].elementName.bundleName}`);
}
}).catch((err) => {
console.error(`getHistoricalSessionDescriptors BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## avSession.getHistoricalSessionDescriptors10+
getHistoricalSessionDescriptors(maxSize: number, callback: AsyncCallback\>>): void
Obtains the descriptors of all sessions. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------------------------ | ---- | -----------------------------------------------------------------|
| maxSize | number | Yes | Maximum number of descriptors to obtain. The value ranges from 0 to 10. If this parameter is left blank, the default value **3** is used.|
| callback | AsyncCallback\>\> | Yes | Callback used to return an array of **AVSessionDescriptor** objects, each of which is read only. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 |Session service exception. |
**Example**
```js
avSession.getHistoricalSessionDescriptors(1, function (err, descriptors) {
if (err) {
console.error(`getHistoricalSessionDescriptors BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors.length : ${descriptors.length}`);
if(descriptors.length > 0 ){
console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].isActive : ${descriptors[0].isActive}`);
console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].type : ${descriptors[0].type}`);
console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].sessionTag : ${descriptors[0].sessionTag}`);
console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].sessionId : ${descriptors[0].sessionId}`);
console.info(`getHistoricalSessionDescriptors : SUCCESS : descriptors[0].elementName.bundleName : ${descriptors[0].elementName.bundleName}`);
}
}
});
```
## avSession.createController
createController(sessionId: string): Promise\
Creates a session controller based on the session ID. Multiple session controllers can be created. This API uses a promise to return the result.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------ | ---- | -------- |
| sessionId | string | Yes | Session ID.|
**Return value**
| Type | Description |
| ----------------------------------------------------- | ------------------------------------------------------------ |
| Promise<[AVSessionController](#avsessioncontroller10)\> | Promise used to return the session controller created, which can be used to obtain the session ID, send commands and events to sessions, and obtain metadata and playback state information.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
let currentAVSession;
let tag = "createNewSession";
let context = featureAbility.getContext();
let sessionId; // Used as an input parameter of subsequent functions.
avSession.createAVSession(context, tag, "audio", function (err, data) {
if (err) {
console.info(`CreateAVSession BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
currentAVSession = data;
sessionId = currentAVSession.sessionId;
console.info(`CreateAVSession : SUCCESS : sessionId = ${sessionId}`);
}
});
let currentAVcontroller;
avSession.createController(sessionId).then((avcontroller) => {
currentAVcontroller = avcontroller;
console.info('CreateController : SUCCESS ');
}).catch((err) => {
console.error(`CreateController BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## avSession.createController
createController(sessionId: string, callback: AsyncCallback\): void
Creates a session controller based on the session ID. Multiple session controllers can be created. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| sessionId | string | Yes | Session ID. |
| callback | AsyncCallback<[AVSessionController](#avsessioncontroller10)\> | Yes | Callback used to return the session controller created, which can be used to obtain the session ID,
send commands and events to sessions, and obtain metadata and playback state information.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
let currentAVSession;
let tag = "createNewSession";
let context = featureAbility.getContext();
let sessionId; // Used as an input parameter of subsequent functions.
avSession.createAVSession(context, tag, "audio", function (err, data) {
if (err) {
console.info(`CreateAVSession BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
currentAVSession = data;
sessionId = currentAVSession.sessionId;
console.info(`CreateAVSession : SUCCESS : sessionId = ${sessionId}`);
}
});
let currentAVcontroller;
avSession.createController(sessionId, function (err, avcontroller) {
if (err) {
console.error(`CreateController BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
currentAVcontroller = avcontroller;
console.info('CreateController : SUCCESS ');
}
});
```
## avSession.castAudio
castAudio(session: SessionToken | 'all', audioDevices: Array): Promise\
Casts a session to a list of devices. This API uses a promise to return the result.
Before calling this API, import the **ohos.multimedia.audio** module to obtain the descriptors of these audio devices.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description|
| ------------ | -------------- |------|------|
| session | [SessionToken](#sessiontoken) | 'all' | Yes | Session token. **SessionToken** indicates a specific token, and **'all'** indicates all tokens.|
| audioDevices | Array\<[audio.AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor)\> | Yes | Audio devices. |
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If casting is successful, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600104 | The remote session connection failed. |
**Example**
```js
import audio from '@ohos.multimedia.audio';
let audioManager = audio.getAudioManager();
let audioRoutingManager = audioManager.getRoutingManager();
let audioDevices;
await audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data) => {
audioDevices = data;
console.info(`Promise returned to indicate that the device list is obtained.`);
}).catch((err) => {
console.error(`GetDevices BusinessError: code: ${err.code}, message: ${err.message}`);
});
avSession.castAudio('all', audioDevices).then(() => {
console.info(`CreateController : SUCCESS`);
}).catch((err) => {
console.error(`CreateController BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## avSession.castAudio
castAudio(session: SessionToken | 'all', audioDevices: Array, callback: AsyncCallback\): void
Casts a session to a list of devices. This API uses an asynchronous callback to return the result.
Before calling this API, import the **ohos.multimedia.audio** module to obtain the descriptors of these audio devices.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| ------------ |--------------------------------------------| ---- | ------------------------------------------------------------ |
| session | [SessionToken](#sessiontoken) | 'all' | Yes | Session token. **SessionToken** indicates a specific token, and **'all'** indicates all tokens.|
| audioDevices | Array\<[audio.AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor)\> | Yes | Audio devices.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the casting is successful, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600104 | The remote session connection failed. |
**Example**
```js
import audio from '@ohos.multimedia.audio';
let audioManager = audio.getAudioManager();
let audioRoutingManager = audioManager.getRoutingManager();
let audioDevices;
await audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data) => {
audioDevices = data;
console.info(`Promise returned to indicate that the device list is obtained.`);
}).catch((err) => {
console.error(`GetDevices BusinessError: code: ${err.code}, message: ${err.message}`);
});
avSession.castAudio('all', audioDevices, function (err) {
if (err) {
console.error(`CastAudio BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`CastAudio : SUCCESS `);
}
});
```
## SessionToken
Describes the information about a session token.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
| Name | Type | Mandatory| Description |
| :-------- | :----- | :--- | :----------- |
| sessionId | string | Yes | Session ID. |
| pid | number | No | Process ID of the session.|
| uid | number | No | User ID. |
## avSession.on('sessionCreate')
on(type: 'sessionCreate', callback: (session: AVSessionDescriptor) => void): void
Subscribes to session creation events.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'sessionCreate'** is triggered when a session is created.|
| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | Yes | Callback used to report the session descriptor.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
avSession.on('sessionCreate', (descriptor) => {
console.info(`on sessionCreate : isActive : ${descriptor.isActive}`);
console.info(`on sessionCreate : type : ${descriptor.type}`);
console.info(`on sessionCreate : sessionTag : ${descriptor.sessionTag}`);
});
```
## avSession.on('sessionDestroy')
on(type: 'sessionDestroy', callback: (session: AVSessionDescriptor) => void): void
Subscribes to session destruction events.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------| ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'sessionDestroy'** is triggered when a session is destroyed.|
| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | Yes | Callback used to report the session descriptor.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
avSession.on('sessionDestroy', (descriptor) => {
console.info(`on sessionDestroy : isActive : ${descriptor.isActive}`);
console.info(`on sessionDestroy : type : ${descriptor.type}`);
console.info(`on sessionDestroy : sessionTag : ${descriptor.sessionTag}`);
});
```
## avSession.on('topSessionChange')
on(type: 'topSessionChange', callback: (session: AVSessionDescriptor) => void): void
Subscribes to top session change events.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------| ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'topSessionChange'** is triggered when the top session is changed.|
| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | Yes | Callback used to report the session descriptor.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
avSession.on('topSessionChange', (descriptor) => {
console.info(`on topSessionChange : isActive : ${descriptor.isActive}`);
console.info(`on topSessionChange : type : ${descriptor.type}`);
console.info(`on topSessionChange : sessionTag : ${descriptor.sessionTag}`);
});
```
## avSession.off('sessionCreate')
off(type: 'sessionCreate', callback?: (session: AVSessionDescriptor) => void): void
Unsubscribes from session creation events.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------| ---- | ----------|
| type | string | Yes | Event type, which is **'sessionCreate'** in this case.|
| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **session** parameter in the callback describes a media session. The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
avSession.off('sessionCreate');
```
## avSession.off('sessionDestroy')
off(type: 'sessionDestroy', callback?: (session: AVSessionDescriptor) => void): void
Unsubscribes from session destruction events.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -----------| ---- | -------------------------|
| type | string | Yes | Event type, which is **'sessionDestroy'** in this case.|
| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **session** parameter in the callback describes a media session. The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
avSession.off('sessionDestroy');
```
## avSession.off('topSessionChange')
off(type: 'topSessionChange', callback?: (session: AVSessionDescriptor) => void): void
Unsubscribes from top session change events.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -----------------| ---- | ---------------------------- |
| type | string | Yes | Event type, which is **'topSessionChange'** in this case.|
| callback | (session: [AVSessionDescriptor](#avsessiondescriptor)) => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **session** parameter in the callback describes a media session. The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
avSession.off('topSessionChange');
```
## avSession.on('sessionServiceDie')
on(type: 'sessionServiceDie', callback: () => void): void
Subscribes to session service death events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'sessionServiceDie'** is triggered when the session service dies.|
| callback | callback: () => void | Yes | Callback used for subscription. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
avSession.on('sessionServiceDie', () => {
console.info(`on sessionServiceDie : session is Died `);
});
```
## avSession.off('sessionServiceDie')
off(type: 'sessionServiceDie', callback?: () => void): void
Unsubscribes from session service death events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ------ | ---------------------- | ---- | ------------------------------------------------------- |
| type | string | Yes | Event type. The event **'sessionServiceDie'** is triggered when the session service dies.|
| callback | callback: () => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
avSession.off('sessionServiceDie');
```
## avSession.sendSystemAVKeyEvent
sendSystemAVKeyEvent(event: KeyEvent, callback: AsyncCallback\): void
Sends a system key event to the top session. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------- |
| event | [KeyEvent](js-apis-keyevent.md) | Yes | Key event. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the event is sent, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600105 | Invalid session command. |
**Example**
```js
let keyItem = {code:0x49, pressedTime:2, deviceId:0};
let event = {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};
avSession.sendSystemAVKeyEvent(event, function (err) {
if (err) {
console.error(`SendSystemAVKeyEvent BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`SendSystemAVKeyEvent : SUCCESS `);
}
});
```
## avSession.sendSystemAVKeyEvent
sendSystemAVKeyEvent(event: KeyEvent): Promise\
Sends a system key event to the top session. This API uses a promise to return the result.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------------- | ---- | ---------- |
| event | [KeyEvent](js-apis-keyevent.md) | Yes | Key event.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the event is sent, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600105 | Invalid session command. |
**Example**
```js
let keyItem = {code:0x49, pressedTime:2, deviceId:0};
let event = {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};
avSession.sendSystemAVKeyEvent(event).then(() => {
console.info(`SendSystemAVKeyEvent Successfully`);
}).catch((err) => {
console.error(`SendSystemAVKeyEvent BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## avSession.sendSystemControlCommand
sendSystemControlCommand(command: AVControlCommand, callback: AsyncCallback\): void
Sends a system control command to the top session. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| command | [AVControlCommand](#avcontrolcommand10) | Yes | Command to send. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the command is sent, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600105 | Invalid session command. |
| 6600107 | Too many commands or events. |
**Example**
```js
let cmd : avSession.AVControlCommandType = 'play';
// let cmd : avSession.AVControlCommandType = 'pause';
// let cmd : avSession.AVControlCommandType = 'stop';
// let cmd : avSession.AVControlCommandType = 'playNext';
// let cmd : avSession.AVControlCommandType = 'playPrevious';
// let cmd : avSession.AVControlCommandType = 'fastForward';
// let cmd : avSession.AVControlCommandType = 'rewind';
let avcommand = {command:cmd};
// let cmd : avSession.AVControlCommandType = 'seek';
// let avcommand = {command:cmd, parameter:10};
// let cmd : avSession.AVControlCommandType = 'setSpeed';
// let avcommand = {command:cmd, parameter:2.6};
// let cmd : avSession.AVControlCommandType = 'setLoopMode';
// let avcommand = {command:cmd, parameter:avSession.LoopMode.LOOP_MODE_SINGLE};
// let cmd : avSession.AVControlCommandType = 'toggleFavorite';
// let avcommand = {command:cmd, parameter:"false"};
avSession.sendSystemControlCommand(avcommand, function (err) {
if (err) {
console.error(`SendSystemControlCommand BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`sendSystemControlCommand successfully`);
}
});
```
## avSession.sendSystemControlCommand
sendSystemControlCommand(command: AVControlCommand): Promise\
Sends a system control command to the top session. This API uses a promise to return the result.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ----------------------------------- |
| command | [AVControlCommand](#avcontrolcommand10) | Yes | Command to send.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the command is sent, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600105 | Invalid session command. |
| 6600107 | Too many commands or events. |
**Example**
```js
let cmd : avSession.AVControlCommandType = 'play';
// let cmd : avSession.AVControlCommandType = 'pause';
// let cmd : avSession.AVControlCommandType = 'stop';
// let cmd : avSession.AVControlCommandType = 'playNext';
// let cmd : avSession.AVControlCommandType = 'playPrevious';
// let cmd : avSession.AVControlCommandType = 'fastForward';
// let cmd : avSession.AVControlCommandType = 'rewind';
let avcommand = {command:cmd};
// let cmd : avSession.AVControlCommandType = 'seek';
// let avcommand = {command:cmd, parameter:10};
// let cmd : avSession.AVControlCommandType = 'setSpeed';
// let avcommand = {command:cmd, parameter:2.6};
// let cmd : avSession.AVControlCommandType = 'setLoopMode';
// let avcommand = {command:cmd, parameter:avSession.LoopMode.LOOP_MODE_SINGLE};
// let cmd : avSession.AVControlCommandType = 'toggleFavorite';
// let avcommand = {command:cmd, parameter:"false"};
avSession.sendSystemControlCommand(avcommand).then(() => {
console.info(`SendSystemControlCommand successfully`);
}).catch((err) => {
console.error(`SendSystemControlCommand BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## ProtocolType10+
Enumerates the protocol types supported by the remote device.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
| Name | Value | Description |
| --------------------------- | ---- | ----------- |
| TYPE_LOCAL | 0 | Local device. |
| TYPE_CAST_PLUS_MIRROR | 1 | Cast+ mirror mode.|
| TYPE_CAST_PLUS_STREAM | 2 | Cast+ stream mode.|
## avSession.startCastDeviceDiscovery10+
startCastDeviceDiscovery(callback: AsyncCallback\): void
Starts cast-enabled device discovery. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the command is sent and device discovery starts, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```js
avSession.startCastDeviceDiscovery(function (err) {
if (err) {
console.error(`startCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`startCastDeviceDiscovery successfully`);
}
});
```
## avSession.startCastDeviceDiscovery10+
startCastDeviceDiscovery(filter: number, callback: AsyncCallback\): void
Starts cast-enabled device discovery with filter criteria specified. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| filter | number | Yes| Filter criteria for device discovery. The value consists of **ProtocolType**s.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the command is sent and device discovery starts, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```js
let filter = 2;
avSession.startCastDeviceDiscovery(filter, function (err) {
if (err) {
console.error(`startCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`startCastDeviceDiscovery successfully`);
}
});
```
## avSession.startCastDeviceDiscovery10+
startCastDeviceDiscovery(filter?: number): Promise\
Starts cast-enabled device discovery. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| filter | number | No| Filter criteria for device discovery. The value consists of **ProtocolType**s.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the command is sent and device discovery starts, no value is returned; otherwise, an error object is returned.|
**Example**
```js
let filter = 2;
avSession.startCastDeviceDiscovery(filter).then(() => {
console.info(`startCastDeviceDiscovery successfully`);
}).catch((err) => {
console.error(`startCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## avSession.stopCastDeviceDiscovery10+
stopCastDeviceDiscovery(callback: AsyncCallback\): void
Stops cast-enabled device discovery. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If device discovery stops, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```js
avSession.stopCastDeviceDiscovery(function (err) {
if (err) {
console.error(`stopCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`stopCastDeviceDiscovery successfully`);
}
});
```
## avSession.stopCastDeviceDiscovery10+
stopCastDeviceDiscovery(): Promise\
Stops cast-enabled device discovery. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If device discovery stops, no value is returned; otherwise, an error object is returned.|
**Example**
```js
avSession.stopCastDeviceDiscovery().then(() => {
console.info(`startCastDeviceDiscovery successfully`);
}).catch((err) => {
console.error(`startCastDeviceDiscovery BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## avSession.setDiscoverable10+
setDiscoverable(enable: boolean, callback: AsyncCallback\): void
Sets whether to allow the device discoverable. A discoverable device can be used as the cast receiver. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| enable | boolean | Yes| Whether to allow the device discoverable. The value **true** means to allow the device discoverable, and **false** means the opposite.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the setting is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Example**
```js
avSession.setDiscoverable(true, function (err) {
if (err) {
console.error(`setDiscoverable BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`setDiscoverable successfully`);
}
});
```
## avSession.setDiscoverable10+
setDiscoverable(enable: boolean): Promise\
Sets whether to allow the device discoverable. A discoverable device can be used as the cast receiver. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| enable | boolean | Yes| Whether to allow the device discoverable. The value **true** means to allow the device discoverable, and **false** means the opposite.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the setting is successful, no value is returned; otherwise, an error object is returned.|
**Example**
```js
avSession.setDiscoverable(true).then(() => {
console.info(`setDiscoverable successfully`);
}).catch((err) => {
console.error(`setDiscoverable BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## avSession.on('deviceAvailable')10+
on(type: 'deviceAvailable', callback: (device: OutputDeviceInfo) => void): void
Subscribes to device discovery events.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'deviceAvailable'** is triggered when a device is discovered.|
| callback | (device: OutputDeviceInfo) => void | Yes | Callback used for subscription. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
let castDevice;
avSession.on('deviceAvailable', (device) => {
castDevice = device;
console.info(`on deviceAvailable : ${device} `);
});
```
## avSession.off('deviceAvailable')10+
off(type: 'deviceAvailable', callback?: (device: OutputDeviceInfo) => void): void
Unsubscribes from device discovery events.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| ------ | ---------------------- | ---- | ------------------------------------------------------- |
| type | string | Yes | Event type. The event **'deviceAvailable'** is triggered when a device is discovered.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
avSession.off('deviceAvailable');
```
## avSession.getAVCastController10+
getAVCastController(sessionId: string, callback: AsyncCallback\): void
Obtains the cast controller when a casting connection is set up. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| sessionId | string | Yes |Session ID.|
| callback | AsyncCallback<[AVCastController](#avcastcontroller10)\> | Yes | Callback used to return the cast controller.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | session does not exist |
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
let currentAVSession;
let tag = "createNewSession";
let context = featureAbility.getContext();
let sessionId; // Used as an input parameter of subsequent functions.
avSession.createAVSession(context, tag, "audio", function (err, data) {
if (err) {
console.info(`CreateAVSession BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
currentAVSession = data;
sessionId = currentAVSession.sessionId;
console.info(`CreateAVSession : SUCCESS : sessionId = ${sessionId}`);
}
});
let aVCastController;
avSession.getAVCastController(sessionId ,function (err, avcontroller) {
if (err) {
console.error(`getAVCastController BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
aVCastController = avcontroller;
console.info('getAVCastController : SUCCESS ');
}
});
```
## avSession.getAVCastController10+
getAVCastController(sessionId: string): Promise\;
Obtains the cast controller when a casting connection is set up. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ------------------------- | ---- | ------------------------------------------------------------ |
| sessionId | string | Yes |Session ID.|
**Return value**
| Type | Description |
| --------- | ------------------------------------------------------------ |
| Promise<[AVCastController](#avcastcontroller10)\> | Promise used to return the cast controller.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | server exception |
| 6600102 | The session does not exist |
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
let currentAVSession;
let tag = "createNewSession";
let context = featureAbility.getContext();
let sessionId; // Used as an input parameter of subsequent functions.
avSession.createAVSession(context, tag, "audio", function (err, data) {
if (err) {
console.info(`CreateAVSession BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
currentAVSession = data;
sessionId = currentAVSession.sessionId;
console.info(`CreateAVSession : SUCCESS : sessionId = ${sessionId}`);
}
});
let aVCastController;
avSession.getAVCastController(sessionId).then((avcontroller) => {
aVCastController = avcontroller;
console.info('getAVCastController : SUCCESS');
}).catch((err) => {
console.error(`getAVCastController BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## avSession.startCasting10+
startCasting(session: SessionToken, device: OutputDeviceInfo, callback: AsyncCallback\): void
Starts casting. This API uses an asynchronous callback to return the result.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| session | [SessionToken](#sessiontoken) | Yes | Session token. |
| device | [OutputDeviceInfo](#outputdeviceinfo10) | Yes | Device-related information.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the command is sent and casting starts, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600108 | Device connecting failed. |
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
let currentAVSession;
let tag = "createNewSession";
let context = featureAbility.getContext();
let currSessionId; // Used as an input parameter of subsequent functions.
avSession.createAVSession(context, tag, "audio", function (err, data) {
if (err) {
console.info(`CreateAVSession BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
currentAVSession = data;
currSessionId = currentAVSession.sessionId;
console.info(`CreateAVSession : SUCCESS : sessionId = ${currSessionId}`);
}
});
let myToken = {
sessionId: currSessionId,
}
let castDevice;
avSession.on('deviceAvailable', (device) => {
castDevice = device;
console.info(`on deviceAvailable : ${device} `);
});
avSession.startCasting(myToken, castDevice, function (err) {
if (err) {
console.error(`startCasting BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`startCasting successfully`);
}
});
```
## avSession.startCasting10+
startCasting(session: SessionToken, device: OutputDeviceInfo): Promise\
Starts casting. This API uses a promise to return the result.
**Required permissions**: ohos.permission.MANAGE_MEDIA_RESOURCES (available only to system applications)
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| session | [SessionToken](#sessiontoken) | Yes | Session token. |
| device | [OutputDeviceInfo](#outputdeviceinfo10) | Yes | Device-related information.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the command is sent and casting starts, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600108 | Device connecting failed. |
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
let currentAVSession;
let tag = "createNewSession";
let context = featureAbility.getContext();
let currSessionId; // Used as an input parameter of subsequent functions.
avSession.createAVSession(context, tag, "audio", function (err, data) {
if (err) {
console.info(`CreateAVSession BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
currentAVSession = data;
currSessionId = currentAVSession.sessionId;
console.info(`CreateAVSession : SUCCESS : sessionId = ${currSessionId}`);
}
});
let myToken = {
sessionId: currSessionId,
}
let castDevice;
avSession.on('deviceAvailable', (device) => {
castDevice = device;
console.info(`on deviceAvailable : ${device} `);
});
avSession.startCasting(myToken, castDevice).then(() => {
console.info(`startCasting successfully`);
}).catch((err) => {
console.error(`startCasting BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## avSession.stopCasting10+
stopCasting(session: SessionToken, callback: AsyncCallback\): void
Stops castings. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| session | [SessionToken](#sessiontoken) | Yes | Session token. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If casting stops, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600109 | The remote connection is not established. |
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
let currentAVSession;
let tag = "createNewSession";
let context = featureAbility.getContext();
let currSessionId; // Used as an input parameter of subsequent functions.
avSession.createAVSession(context, tag, "audio", function (err, data) {
if (err) {
console.info(`CreateAVSession BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
currentAVSession = data;
currSessionId = currentAVSession.sessionId;
console.info(`CreateAVSession : SUCCESS : sessionId = ${currSessionId}`);
}
});
let myToken = {
sessionId: currSessionId,
}
avSession.stopCasting(myToken, function (err) {
if (err) {
console.error(`stopCasting BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`stopCasting successfully`);
}
});
```
## avSession.stopCasting10+
stopCasting(session: SessionToken): Promise\
Stops castings. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| session | [SessionToken](#sessiontoken) | Yes | Session token. |
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If casting stops, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600109 | The remote connection is not established. |
**Example**
```js
import featureAbility from '@ohos.ability.featureAbility';
let currentAVSession;
let tag = "createNewSession";
let context = featureAbility.getContext();
let currSessionId; // Used as an input parameter of subsequent functions.
avSession.createAVSession(context, tag, "audio", function (err, data) {
if (err) {
console.info(`CreateAVSession BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
currentAVSession = data;
currSessionId = currentAVSession.sessionId;
console.info(`CreateAVSession : SUCCESS : sessionId = ${currSessionId}`);
}
});
let myToken = {
sessionId: currSessionId,
}
avSession.stopCasting(myToken).then(() => {
console.info(`stopCasting successfully`);
}).catch((err) => {
console.error(`stopCasting BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## AVSessionType10+
Enumerates the session types supported by the session.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Type | Description|
| ----- | ------ | ---- |
| audio | string | Audio session.|
| video | string | Video session.|
## AVSession10+
An **AVSession** object is created by calling [avSession.createAVSession](#avsessioncreateavsession10). The object enables you to obtain the session ID and set the metadata and playback state.
### Attributes
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Type | Readable| Writable| Description |
| :-------- | :----- | :--- | :--- | :---------------------------- |
| sessionId | string | Yes | No | Unique session ID of the **AVSession** object.|
| sessionType10+ | AVSessionType | Yes | No | AVSession type.|
**Example**
```js
let sessionId = currentAVSession.sessionId;
let sessionType = currentAVSession.sessionType;
```
### setAVMetadata10+
setAVMetadata(data: AVMetadata): Promise\
Sets session metadata. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------- | ---- | ------------ |
| data | [AVMetadata](#avmetadata10) | Yes | Session metadata.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the setting is successful, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
let metadata = {
assetId: "121278",
title: "lose yourself",
artist: "Eminem",
author: "ST",
album: "Slim shady",
writer: "ST",
composer: "ST",
duration: 2222,
mediaImage: "https://www.example.com/example.jpg",
subtitle: "8 Mile",
description: "Rap",
lyric: "https://www.example.com/example.lrc",
previousAssetId: "121277",
nextAssetId: "121279",
};
currentAVSession.setAVMetadata(metadata).then(() => {
console.info(`SetAVMetadata successfully`);
}).catch((err) => {
console.error(`SetAVMetadata BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### setAVMetadata10+
setAVMetadata(data: AVMetadata, callback: AsyncCallback\): void
Sets session metadata. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ------------------------------------- |
| data | [AVMetadata](#avmetadata10) | Yes | Session metadata. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the setting is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
let metadata = {
assetId: "121278",
title: "lose yourself",
artist: "Eminem",
author: "ST",
album: "Slim shady",
writer: "ST",
composer: "ST",
duration: 2222,
mediaImage: "https://www.example.com/example.jpg",
subtitle: "8 Mile",
description: "Rap",
lyric: "https://www.example.com/example.lrc",
previousAssetId: "121277",
nextAssetId: "121279",
};
currentAVSession.setAVMetadata(metadata, function (err) {
if (err) {
console.error(`SetAVMetadata BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`SetAVMetadata successfully`);
}
});
```
### setAVPlaybackState10+
setAVPlaybackState(state: AVPlaybackState): Promise\
Sets information related to the session playback state. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ----------------------------------- | ---- | ---------------------------------------------- |
| data | [AVPlaybackState](#avplaybackstate10) | Yes | Information related to the session playback state.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the setting is successful, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
let playbackState = {
state:avSession.PlaybackState.PLAYBACK_STATE_PLAY,
speed: 1.0,
position:{elapsedTime:10, updateTime:(new Date()).getTime()},
bufferedTime:1000,
loopMode:avSession.LoopMode.LOOP_MODE_SINGLE,
isFavorite:true,
};
currentAVSession.setAVPlaybackState(playbackState).then(() => {
console.info(`SetAVPlaybackState successfully`);
}).catch((err) => {
console.info(`SetAVPlaybackState BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### setAVPlaybackState10+
setAVPlaybackState(state: AVPlaybackState, callback: AsyncCallback\): void
Sets information related to the session playback state. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------- | ---- | ---------------------------------------------- |
| data | [AVPlaybackState](#avplaybackstate10) | Yes | Information related to the session playback state.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the setting is successful, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
let PlaybackState = {
state:avSession.PlaybackState.PLAYBACK_STATE_PLAY,
speed: 1.0,
position:{elapsedTime:10, updateTime:(new Date()).getTime()},
bufferedTime:1000,
loopMode:avSession.LoopMode.LOOP_MODE_SINGLE,
isFavorite:true,
};
currentAVSession.setAVPlaybackState(PlaybackState, function (err) {
if (err) {
console.info(`SetAVPlaybackState BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`SetAVPlaybackState successfully`);
}
});
```
### setLaunchAbility10+
setLaunchAbility(ability: WantAgent): Promise\
Sets a launcher ability. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | --------------------------------------------- | ---- | ----------------------------------------------------------- |
| ability | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes | Application attributes, such as the bundle name, ability name, and deviceID.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the setting is successful, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
import wantAgent from '@ohos.app.ability.wantAgent';
// WantAgentInfo object
let wantAgentInfo = {
wants: [
{
deviceId: "deviceId",
bundleName: "com.example.myapplication",
abilityName: "EntryAbility",
action: "action1",
entities: ["entity1"],
type: "MIMETYPE",
uri: "key={true,true,false}",
parameters:
{
mykey0: 2222,
mykey1: [1, 2, 3],
mykey2: "[1, 2, 3]",
mykey3: "ssssssssssssssssssssssssss",
mykey4: [false, true, false],
mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"],
mykey6: true,
}
}
],
operationType: wantAgent.OperationType.START_ABILITIES,
requestCode: 0,
wantAgentFlags:[wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
}
wantAgent.getWantAgent(wantAgentInfo).then((agent) => {
currentAVSession.setLaunchAbility(agent).then(() => {
console.info(`SetLaunchAbility successfully`);
}).catch((err) => {
console.error(`SetLaunchAbility BusinessError: code: ${err.code}, message: ${err.message}`);
});
});
```
### setLaunchAbility10+
setLaunchAbility(ability: WantAgent, callback: AsyncCallback\): void
Sets a launcher ability. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
| ability | [WantAgent](js-apis-app-ability-wantAgent.md) | Yes | Application attributes, such as the bundle name, ability name, and deviceID. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the setting is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
import wantAgent from '@ohos.app.ability.wantAgent';
// WantAgentInfo object
let wantAgentInfo = {
wants: [
{
deviceId: "deviceId",
bundleName: "com.example.myapplication",
abilityName: "EntryAbility",
action: "action1",
entities: ["entity1"],
type: "MIMETYPE",
uri: "key={true,true,false}",
parameters:
{
mykey0: 2222,
mykey1: [1, 2, 3],
mykey2: "[1, 2, 3]",
mykey3: "ssssssssssssssssssssssssss",
mykey4: [false, true, false],
mykey5: ["qqqqq", "wwwwww", "aaaaaaaaaaaaaaaaa"],
mykey6: true,
}
}
],
operationType: wantAgent.OperationType.START_ABILITIES,
requestCode: 0,
wantAgentFlags:[wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
}
wantAgent.getWantAgent(wantAgentInfo).then((agent) => {
currentAVSession.setLaunchAbility(agent, function (err) {
if (err) {
console.error(`SetLaunchAbility BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`SetLaunchAbility successfully`);
}
});
});
```
### dispatchSessionEvent10+
dispatchSessionEvent(event: string, args: {[key: string]: Object}): Promise\
Dispatches a custom event in the session, including the event name and event content in key-value pair format. This API uses a promise to return the result. It is called by the provider.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | --------------------------------------------- | ---- | ----------------------------------------------------------- |
| event | string | Yes | Name of the session event.|
| args | {[key: string]: any} | Yes | Event content in key-value pair format.|
> **NOTE**
>
> The **args** parameter supports the following data types: string, number, Boolean, object, array, and file descriptor. For details, see [@ohos.app.ability.Want (Want)](./js-apis-app-ability-want.md).
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the setting is successful, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
let eventName = "dynamic_lyric";
let args = {
lyric : "This is lyric"
}
currentAVSession.dispatchSessionEvent(eventName, args).catch((err) => {
console.info(`dispatchSessionEvent BusinessError: code: ${err.code}, message: ${err.message}`);
})
```
### dispatchSessionEvent10+
dispatchSessionEvent(event: string, args: {[key: string]: Object}, callback: AsyncCallback\): void
Dispatches a custom event in the session, including the event name and event content in key-value pair format. This API uses an asynchronous callback to return the result. It is called by the provider.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | --------------------------------------------- | ---- | ----------------------------------------------------------- |
| event | string | Yes | Name of the session event.|
| args | {[key: string]: any} | Yes | Event content in key-value pair format.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the setting is successful, **err** is **undefined**; otherwise, **err** is an error object.|
> **NOTE**
>
> The **args** parameter supports the following data types: string, number, Boolean, object, array, and file descriptor. For details, see [@ohos.app.ability.Want (Want)](./js-apis-app-ability-want.md).
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
let eventName = "dynamic_lyric";
let args = {
lyric : "This is lyric"
}
currentAVSession.dispatchSessionEvent(eventName, args, (err) => {
if(err) {
console.error(`dispatchSessionEvent BusinessError: code: ${err.code}, message: ${err.message}`);
}
})
```
### setAVQueueItems10+
setAVQueueItems(items: Array\): Promise\
Sets a playlist. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------ | ------------------------------------ | ---- | ---------------------------------- |
| items | Array<[AVQueueItem](#avqueueitem10)\> | Yes | Playlist to set.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the setting is successful, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
import image from '@ohos.multimedia.image';
import resourceManager from '@ohos.resourceManager';
let value : Uint8Array = await resourceManager.getRawFileContent('IMAGE_URI');
let imageSource : imageImageSource = image.createImageSource(value.buffer);
let imagePixel : image.PixelMap = await imageSource.createPixelMap({desiredSize:{width: 150, height: 150}});
let queueItemDescription_1 = {
mediaId: '001',
title: 'music_name',
subtitle: 'music_sub_name',
description: 'music_description',
icon : imagePixel,
iconUri: 'http://www.icon.uri.com',
extras: {'extras':'any'}
};
let queueItem_1 = {
itemId: 1,
description: queueItemDescription_1
};
let queueItemDescription_2 = {
mediaId: '002',
title: 'music_name',
subtitle: 'music_sub_name',
description: 'music_description',
icon: imagePixel,
iconUri: 'http://www.xxx.com',
extras: {'extras':'any'}
};
let queueItem_2 = {
itemId: 2,
description: queueItemDescription_2
};
let queueItemsArray = [queueItem_1, queueItem_2];
currentAVSession.setAVQueueItems(queueItemsArray).then(() => {
console.info(`SetAVQueueItems successfully`);
}).catch((err) => {
console.error(`SetAVQueueItems BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### setAVQueueItems10+
setAVQueueItems(items: Array\, callback: AsyncCallback\): void
Sets a playlist. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------ | ---- | ----------------------------------------------------------- |
| items | Array<[AVQueueItem](#avqueueitem10)\> | Yes | Playlist to set. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the setting is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
import image from '@ohos.multimedia.image';
import resourceManager from '@ohos.resourceManager';
let value : Uint8Array = await resourceManager.getRawFileContent('IMAGE_URI');
let imageSource : imageImageSource = image.createImageSource(value.buffer);
let imagePixel : image.PixelMap = await imageSource.createPixelMap({desiredSize:{width: 150, height: 150}});
let queueItemDescription_1 = {
mediaId: '001',
title: 'music_name',
subtitle: 'music_sub_name',
description: 'music_description',
icon: imagePixel,
iconUri: 'http://www.icon.uri.com',
extras: {'extras':'any'}
};
let queueItem_1 = {
itemId: 1,
description: queueItemDescription_1
};
let queueItemDescription_2 = {
mediaId: '002',
title: 'music_name',
subtitle: 'music_sub_name',
description: 'music_description',
icon: imagePixel,
iconUri: 'http://www.icon.uri.com',
extras: {'extras':'any'}
};
let queueItem_2 = {
itemId: 2,
description: queueItemDescription_2
};
let queueItemsArray = [queueItem_1, queueItem_2];
currentAVSession.setAVQueueItems(queueItemsArray, function (err) {
if (err) {
console.error(`SetAVQueueItems BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`SetAVQueueItems successfully`);
}
});
```
### setAVQueueTitle10+
setAVQueueTitle(title: string): Promise\
Sets a name for the playlist. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------ | ------ | ---- | -------------- |
| title | string | Yes | Name of the playlist.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the setting is successful, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
let queueTitle = 'QUEUE_TITLE';
currentAVSession.setAVQueueTitle(queueTitle).then(() => {
console.info(`SetAVQueueTitle successfully`);
}).catch((err) => {
console.error(`SetAVQueueTitle BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### setAVQueueTitle10+
setAVQueueTitle(title: string, callback: AsyncCallback\): void
Sets a name for the playlist. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------- | ---- | ----------------------------------------------------------- |
| title | string | Yes | Name of the playlist. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the setting is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
let queueTitle = 'QUEUE_TITLE';
currentAVSession.setAVQueueTitle(queueTitle, function (err) {
if (err) {
console.info(`SetAVQueueTitle BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.error(`SetAVQueueTitle successfully`);
}
});
```
### setExtras10+
setExtras(extras: {[key: string]: Object}): Promise\
Sets a custom media packet in the form of key-value pairs. This API uses a promise to return the result. It is called by the provider.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | --------------------------------------------- | ---- | ----------------------------------------------------------- |
| extras | {[key: string]: Object} | Yes | Key-value pairs of the custom media packet.|
> **NOTE**
>
> The **extras** parameter supports the following data types: string, number, Boolean, object, array, and file descriptor. For details, see [@ohos.app.ability.Want (Want)](./js-apis-app-ability-want.md).
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the setting is successful, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
let extras = {
extras : "This is custom media packet"
}
currentAVSession.setExtras(extras).catch((err) => {
console.info(`setExtras BusinessError: code: ${err.code}, message: ${err.message}`);
})
```
### setExtras10+
setExtras(extras: {[key: string]: Object}, callback: AsyncCallback\): void
Sets a custom media packet in the form of key-value pairs. This API uses an asynchronous callback to return the result. It is called by the provider.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | --------------------------------------------- | ---- | ----------------------------------------------------------- |
| extras | {[key: string]: any} | Yes | Key-value pairs of the custom media packet.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the setting is successful, **err** is **undefined**; otherwise, **err** is an error object.|
> **NOTE**
>
> The **extras** parameter supports the following data types: string, number, Boolean, object, array, and file descriptor. For details, see [@ohos.app.ability.Want (Want)](./js-apis-app-ability-want.md).
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
let extras = {
extras : "This is custom media packet"
}
currentAVSession.setExtras(extras, (err) => {
if(err) {
console.error(`setExtras BusinessError: code: ${err.code}, message: ${err.message}`);
}
})
```
### getController10+
getController(): Promise\
Obtains the controller corresponding to this session. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| ---------------------------------------------------- | ----------------------------- |
| Promise<[AVSessionController](#avsessioncontroller10)> | Promise used to return the session controller.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
let avsessionController;
currentAVSession.getController().then((avcontroller) => {
avsessionController = avcontroller;
console.info(`GetController : SUCCESS : sessionid : ${avsessionController.sessionId}`);
}).catch((err) => {
console.error(`GetController BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### getController10+
getController(callback: AsyncCallback\): void
Obtains the controller corresponding to this session. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------------- | ---- | -------------------------- |
| callback | AsyncCallback<[AVSessionController](#avsessioncontroller10)\> | Yes | Callback used to return the session controller.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
let avsessionController;
currentAVSession.getController(function (err, avcontroller) {
if (err) {
console.error(`GetController BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
avsessionController = avcontroller;
console.info(`GetController : SUCCESS : sessionid : ${avsessionController.sessionId}`);
}
});
```
### getAVCastController10+
getAVCastController(callback: AsyncCallback\): void
Obtains the cast controller when a casting connection is set up. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback<[AVCastController](#avcastcontroller10)\> | Yes | Callback used to return the cast controller.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600102 | The session does not exist. |
| 6600110 | The remote connection is not established. |
**Example**
```js
let aVCastController;
currentAVSession.getAVCastController().then((avcontroller) => {
aVCastController = avcontroller;
console.info(`getAVCastController : SUCCESS : sessionid : ${aVCastController.sessionId}`);
}).catch((err) => {
console.error(`getAVCastController BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### getAVCastController10+
getAVCastController(): Promise\;
Obtains the cast controller when a casting connection is set up. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Return value**
| Type | Description |
| --------- | ------------------------------------------------------------ |
| Promise<[AVCastController](#avcastcontroller10)\> | Promise used to return the cast controller.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600102 | The session does not exist. |
| 6600110 | The remote connection is not established. |
**Example**
```js
let aVCastController;
currentAVSession.getAVCastController(function (err, avcontroller) {
if (err) {
console.error(`getAVCastController BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
aVCastController = avcontroller;
console.info(`getAVCastController : SUCCESS : sessionid : ${aVCastController.sessionId}`);
}
});
```
### getOutputDevice10+
getOutputDevice(): Promise\
Obtains information about the output device for this session. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| ---------------------------------------------- | --------------------------------- |
| Promise<[OutputDeviceInfo](#outputdeviceinfo10)> | Promise used to return the output device information.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.getOutputDevice().then((outputDeviceInfo) => {
console.info(`GetOutputDevice : SUCCESS : isRemote : ${outputDeviceInfo.isRemote}`);
}).catch((err) => {
console.error(`GetOutputDevice BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### getOutputDevice10+
getOutputDevice(callback: AsyncCallback\): void
Obtains information about the output device for this session. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | ------------------------------ |
| callback | AsyncCallback<[OutputDeviceInfo](#outputdeviceinfo10)\> | Yes | Callback used to return the information obtained.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.getOutputDevice(function (err, outputDeviceInfo) {
if (err) {
console.error(`GetOutputDevice BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`GetOutputDevice : SUCCESS : isRemote : ${outputDeviceInfo.isRemote}`);
}
});
```
### activate10+
activate(): Promise\
Activates this session. A session can be used only after being activated. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the session is activated, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.activate().then(() => {
console.info(`Activate : SUCCESS `);
}).catch((err) => {
console.error(`Activate BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### activate10+
activate(callback: AsyncCallback\): void
Activates this session. A session can be used only after being activated. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ---------- |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the session is activated, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.activate(function (err) {
if (err) {
console.error(`Activate BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`Activate : SUCCESS `);
}
});
```
### deactivate10+
deactivate(): Promise\
Deactivates this session. You can use [activate](#activate10) to activate the session again. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the session is deactivated, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.deactivate().then(() => {
console.info(`Deactivate : SUCCESS `);
}).catch((err) => {
console.error(`Deactivate BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### deactivate10+
deactivate(callback: AsyncCallback\): void
Deactivates this session. This API uses an asynchronous callback to return the result.
Deactivates this session. You can use [activate](#activate10) to activate the session again.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ---------- |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the session is deactivated, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.deactivate(function (err) {
if (err) {
console.error(`Deactivate BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`Deactivate : SUCCESS `);
}
});
```
### destroy10+
destroy(): Promise\
Destroys this session. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the session is destroyed, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.destroy().then(() => {
console.info(`Destroy : SUCCESS `);
}).catch((err) => {
console.error(`Destroy BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### destroy10+
destroy(callback: AsyncCallback\): void
Destroys this session. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ---------- |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the session is destroyed, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.destroy(function (err) {
if (err) {
console.error(`Destroy BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`Destroy : SUCCESS `);
}
});
```
### on('play')10+
on(type: 'play', callback: () => void): void
Subscribes to playback started events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'play'** is triggered when the command for starting playback is sent to the session.|
| callback | callback: () => void | Yes | Callback used for subscription. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('play', () => {
console.info(`on play entry`);
});
```
### on('pause')10+
on(type: 'pause', callback: () => void): void
Subscribes to playback paused events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'pause'** is triggered when the command for pausing the playback is sent to the session.|
| callback | callback: () => void | Yes | Callback used for subscription. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('pause', () => {
console.info(`on pause entry`);
});
```
### on('stop')10+
on(type:'stop', callback: () => void): void
Subscribes to playback stopped events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'stop'** is triggered when the command for stopping the playback is sent to the session.|
| callback | callback: () => void | Yes | Callback used for subscription. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('stop', () => {
console.info(`on stop entry`);
});
```
### on('playNext')10+
on(type:'playNext', callback: () => void): void
Subscribes to playNext command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'playNext'** is triggered when the command for playing the next item is sent to the session.|
| callback | callback: () => void | Yes | Callback used for subscription. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('playNext', () => {
console.info(`on playNext entry`);
});
```
### on('playPrevious')10+
on(type:'playPrevious', callback: () => void): void
Subscribes to playPrevious command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'playPrevious'** is triggered when the command for playing the previous item sent to the session.|
| callback | callback: () => void | Yes | Callback used for subscription. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('playPrevious', () => {
console.info(`on playPrevious entry`);
});
```
### on('fastForward')10+
on(type: 'fastForward', callback: () => void): void
Subscribes to fastForward command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'fastForward'** is triggered when the command for fast forwarding is sent to the session.|
| callback | callback: () => void | Yes | Callback used for subscription. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('fastForward', () => {
console.info(`on fastForward entry`);
});
```
### on('rewind')10+
on(type:'rewind', callback: () => void): void
Subscribes to rewind command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'rewind'** is triggered when the command for rewinding is sent to the session.|
| callback | callback: () => void | Yes | Callback used for subscription. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('rewind', () => {
console.info(`on rewind entry`);
});
```
### on('seek')10+
on(type: 'seek', callback: (time: number) => void): void
Subscribes to seek command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'seek'** is triggered when the seek command is sent to the session.|
| callback | (time: number) => void | Yes | Callback used for subscription. The **time** parameter in the callback indicates the time to seek to, in milliseconds. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('seek', (time) => {
console.info(`on seek entry time : ${time}`);
});
```
### on('setSpeed')10+
on(type: 'setSpeed', callback: (speed: number) => void): void
Subscribes to setSpeed command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'setSpeed'** is triggered when the command for setting the playback speed is sent to the session.|
| callback | (speed: number) => void | Yes | Callback used for subscription. The **speed** parameter in the callback indicates the playback speed. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('setSpeed', (speed) => {
console.info(`on setSpeed speed : ${speed}`);
});
```
### on('setLoopMode')10+
on(type: 'setLoopMode', callback: (mode: LoopMode) => void): void
Subscribes to setLoopMode command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ---- |
| type | string | Yes | Event type. The event **'setLoopMode'** is triggered when the command for setting the loop mode is sent to the session.|
| callback | (mode: [LoopMode](#loopmode10)) => void | Yes | Callback used for subscription. The **mode** parameter in the callback indicates the loop mode. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('setLoopMode', (mode) => {
console.info(`on setLoopMode mode : ${mode}`);
});
```
### on('toggleFavorite')10+
on(type: 'toggleFavorite', callback: (assetId: string) => void): void
Subscribes to toggleFavorite command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'toggleFavorite'** is triggered when the command for favoriting the media asset is sent to the session.|
| callback | (assetId: string) => void | Yes | Callback used for subscription. The **assetId** parameter in the callback indicates the media asset ID. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('toggleFavorite', (assetId) => {
console.info(`on toggleFavorite mode : ${assetId}`);
});
```
### on('skipToQueueItem')10+
on(type: 'skipToQueueItem', callback: (itemId: number) => void): void
Subscribes to the event that indicates an item in the playlist is selected. The session can play the selected item.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ---------------------------------------------------------------------------------------- |
| type | string | Yes | Event type. The event **'skipToQueueItem'** is triggered when an item in the playlist is selected.|
| callback | (itemId: number) => void | Yes | Callback used for subscription. The **itemId** parameter in the callback indicates the ID of the selected item. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('skipToQueueItem', (itemId) => {
console.info(`on skipToQueueItem id : ${itemId}`);
});
```
### on('handleKeyEvent')10+
on(type: 'handleKeyEvent', callback: (event: KeyEvent) => void): void
Subscribes to key events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'handleKeyEvent'** is triggered when a key event is sent to the session.|
| callback | (event: [KeyEvent](js-apis-keyevent.md)) => void | Yes | Callback used for subscription. The **event** parameter in the callback indicates the key event. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('handleKeyEvent', (event) => {
console.info(`on handleKeyEvent event : ${event}`);
});
```
### on('outputDeviceChange')10+
on(type: 'outputDeviceChange', callback: (state: ConnectionState, device: OutputDeviceInfo) => void): void
Subscribes to output device change events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'outputDeviceChange'** is triggered when the output device changes.|
| callback | (state: [ConnectionState](#connectionstate10), device: [OutputDeviceInfo](#outputdeviceinfo10)) => void | Yes | Callback used for subscription. The **device** parameter in the callback indicates the output device information.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('outputDeviceChange', (state, device) => {
console.info(`on outputDeviceChange device : ${device}`);
});
```
### on('commonCommand')10+
on(type: 'commonCommand', callback: (command: string, args: {[key: string]: Object}) => void): void
Subscribes to custom control command change events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'commonCommand'** is triggered when a custom control command changes.|
| callback | (commonCommand: string, args: {[key:string]: Object}) => void | Yes | Callback used for subscription. The **commonCommand** parameter in the callback indicates the name of the changed custom control command, and **args** indicates the parameters carried in the command. The parameters must be the same as those set in **sendCommand**. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.on('commonCommand', (commonCommand, args) => {
console.info(`OnCommonCommand, the command is ${commonCommand}, args: ${JSON.stringify(args)}`);
});
```
### off('play')10+
off(type: 'play', callback?: () => void): void
Unsubscribes from playback started events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| type | string | Yes | Event type, which is **'play'** in this case.|
| callback | callback: () => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('play');
```
### off('pause')10+
off(type: 'pause', callback?: () => void): void
Unsubscribes from playback paused events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| type | string | Yes | Event type, which is **'pause'** in this case.|
| callback | callback: () => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('pause');
```
### off('stop')10+
off(type: 'stop', callback?: () => void): void
Unsubscribes from playback stopped events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| type | string | Yes | Event type, which is **'stop'** in this case.|
| callback | callback: () => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('stop');
```
### off('playNext')10+
off(type: 'playNext', callback?: () => void): void
Unsubscribes from playNext command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| type | string | Yes | Event type, which is **'playNext'** in this case.|
| callback | callback: () => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('playNext');
```
### off('playPrevious')10+
off(type: 'playPrevious', callback?: () => void): void
Unsubscribes from playPrevious command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| type | string | Yes | Event type, which is **'playPrevious'** in this case.|
| callback | callback: () => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('playPrevious');
```
### off('fastForward')10+
off(type: 'fastForward', callback?: () => void): void
Unsubscribes from fastForward command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| type | string | Yes | Event type, which is **'fastForward'** in this case.|
| callback | callback: () => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('fastForward');
```
### off('rewind')10+
off(type: 'rewind', callback?: () => void): void
Unsubscribes from rewind command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| type | string | Yes | Event type, which is **'rewind'** in this case.|
| callback | callback: () => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('rewind');
```
### off('seek')10+
off(type: 'seek', callback?: (time: number) => void): void
Unsubscribes from seek command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ----------------------------------------- |
| type | string | Yes | Event type, which is **'seek'** in this case. |
| callback | (time: number) => void | No | Callback used for unsubscription. The **time** parameter in the callback indicates the time to seek to, in milliseconds.
If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('seek');
```
### off('setSpeed')10+
off(type: 'setSpeed', callback?: (speed: number) => void): void
Unsubscribes from setSpeed command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------- | ---- | -------------------------------------------|
| type | string | Yes | Event type, which is **'setSpeed'** in this case. |
| callback | (speed: number) => void | No | Callback used for unsubscription. The **speed** parameter in the callback indicates the playback speed.
If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('setSpeed');
```
### off('setLoopMode')10+
off(type: 'setLoopMode', callback?: (mode: LoopMode) => void): void
Unsubscribes from setSpeed command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ----- |
| type | string | Yes | Event type, which is **'setLoopMode'** in this case.|
| callback | (mode: [LoopMode](#loopmode10)) => void | No | Callback used for unsubscription. The **mode** parameter in the callback indicates the loop mode.
If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('setLoopMode');
```
### off('toggleFavorite')10+
off(type: 'toggleFavorite', callback?: (assetId: string) => void): void
Unsubscribes from toggleFavorite command events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------- | ---- | -------------------------------------------------------- |
| type | string | Yes | Event type, which is **'toggleFavorite'** in this case. |
| callback | (assetId: string) => void | No | Callback used for unsubscription. The **assetId** parameter in the callback indicates the media asset ID.
If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('toggleFavorite');
```
### off('skipToQueueItem')10+
off(type: 'skipToQueueItem', callback?: (itemId: number) => void): void
Unsubscribes from the event that indicates an item in the playlist is selected.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------ | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| type | string | Yes | Event type, which is **'skipToQueueItem'** in this case. |
| callback | (itemId: number) => void | No | Callback used for unsubscription. The **itemId** parameter in the callback indicates the ID of the item.
If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('skipToQueueItem');
```
### off('handleKeyEvent')10+
off(type: 'handleKeyEvent', callback?: (event: KeyEvent) => void): void
Unsubscribes from key events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type, which is **'handleKeyEvent'** in this case. |
| callback | (event: [KeyEvent](js-apis-keyevent.md)) => void | No | Callback used for unsubscription. The **event** parameter in the callback indicates the key event.
If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('handleKeyEvent');
```
### off('outputDeviceChange')10+
off(type: 'outputDeviceChange', callback?: (state: ConnectionState, device: OutputDeviceInfo) => void): void
Unsubscribes from playback device change events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------ |
| type | string | Yes | Event type, which is **'outputDeviceChange'** in this case. |
| callback | (state: [ConnectionState](#connectionstate10), device: [OutputDeviceInfo](#outputdeviceinfo10)) => void | No | Callback used for unsubscription. The **device** parameter in the callback indicates the output device information.
If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('outputDeviceChange');
```
### off('commonCommand')10+
off(type: 'commonCommand', callback?: (command: string, args: {[key:string]: Object}) => void): void
Unsubscribes from custom control command change events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
| type | string | Yes | Event type, which is **'commonCommand'** in this case. |
| callback | (command: string, args: {[key:string]: Object}) => void | No | Callback used for unsubscription. The **command** parameter in the callback indicates the name of the changed custom control command, and **args** indicates the parameters carried in the command.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
**Example**
```js
currentAVSession.off('commonCommand');
```
### stopCasting10+
stopCasting(callback: AsyncCallback\): void
Stops castings. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the command is sent, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600109 | The remote connection is not established. |
**Example**
```js
currentAVSession.stopCasting(function (err) {
if (err) {
console.info(`stopCasting BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`stopCasting successfully`);
}
});
```
### stopCasting10+
stopCasting(): Promise\
Stops castings. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If casting stops, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600109 | The remote connection is not established. |
**Example**
```js
currentAVSession.stopCasting().then(() => {
console.info(`stopCasting successfully`);
}).catch((err) => {
console.info(`stopCasting BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
## AVCastControlCommandType10+
Enumerates the commands that can be sent by a cast controller.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
| Name | Type | Description |
| -------------- | ------ | ------------ |
| play | string | Play the media. |
| pause | string | Pause the playback. |
| stop | string | Stop the playback. |
| playNext | string | Play the next media asset. |
| playPrevious | string | Play the previous media asset. |
| fastForward | string | Fast-forward. |
| rewind | string | Rewind. |
| seek | numbder | Seek to a playback position.|
| setSpeed | number | Set the playback speed.|
| setLoopMode | string | Set the loop mode.|
| toggleFavorite | string | Favorite the media asset. |
| setVolume | number | Set the volume. |
## AVCastControlCommand10+
Defines the command that can be sent by a cast controller.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
| Name | Type | Mandatory| Description |
| --------- | ------------------------------------------------- | ---- | -------------- |
| command | [AVCastControlCommandType](#avcastcontrolcommandtype10) | Yes | Command. |
| parameter | [LoopMode](#loopmode10) | string | number | No | Parameters carried in the command.|
## AVCastController10+
After a casting connection is set up, you can call [avSession.getAVCastController](#getavcastcontroller10) to obtain the cast controller. Through the controller, you can query the session ID, send commands and events to a session, and obtain session metadata and playback state information.
### setDisplaySurface10+
setDisplaySurface(surfaceId: string): Promise\
Sets the surface ID for playback, which is used at the cast receiver (sink). This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Return value**
| Type | Description |
| --------------------------------------------- | --------------------------- |
| Promise\ | Promise used to return the result.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600109 | The remote connection is not established. |
**Example**
```js
aVCastController.setDisplaySurface().then(() => {
console.info(`setDisplaySurface : SUCCESS :`);
});
```
### setDisplaySurface10+
setDisplaySurface(surfaceId: string, callback: AsyncCallback\): void
Sets the surface ID for playback, which is used at the cast receiver (sink). This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\ | Yes | Callback used to return the result.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600109 | The remote connection is not established. |
**Example**
```js
aVCastController.setDisplaySurface(function (err, value) {
if (err) {
console.info(`setDisplaySurface BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`setDisplaySurface : SUCCESS : state : ${value}`);
}
});
```
### getAVPlaybackState10+
getAVPlaybackState(callback: AsyncCallback\): void
Obtains the remote playback state. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback<[[AVPlaybackState](#avplaybackstate10)\> | Yes | Callback used to return the remote playback state.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
**Example**
```js
aVCastController.getAVPlaybackState(function (err, state) {
if (err) {
console.error(`getAVPlaybackState BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`getAVPlaybackState : SUCCESS`);
}
});
```
### getAVPlaybackState10+
getAVPlaybackState(): Promise\;
Obtains the remote playback state. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Return value**
| Type | Description |
| --------- | ------------------------------------------------------------ |
| Promise<[AVPlaybackState](#avplaybackstate10)\> | Promise used to return the remote playback state.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
**Example**
```js
aVCastController.getAVPlaybackState().then((state) => {
console.info(`getAVPlaybackState : SUCCESS :`);
}).catch((err) => {
console.error(`getAVPlaybackState BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### sendControlCommand10+
sendControlCommand(command: AVCastControlCommand): Promise\
Sends a control command to the session through the controller. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ------------------------------ |
| command | [AVCastControlCommand](#avcastcontrolcommand10) | Yes | Command to send.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the command is sent, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600105 | Invalid session command. |
| 6600109 | The remote connection is not established. |
**Example**
```js
let avCommand = {command:'play'};
// let avCommand = {command:'pause'};
// let avCommand = {command:'stop'};
// let avCommand = {command:'playNext'};
// let avCommand = {command:'playPrevious'};
// let avCommand = {command:'fastForward'};
// let avCommand = {command:'rewind'};
// let avCommand = {command:'seek', parameter:10};
aVCastController.sendControlCommand(avCommand).then(() => {
console.info(`SendControlCommand successfully`);
}).catch((err) => {
console.error(`SendControlCommand BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### sendControlCommand10+
sendControlCommand(command: AVCastControlCommand, callback: AsyncCallback\): void
Sends a control command to the session through the controller. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------ |
| command | [AVCastControlCommand](#avcastcontrolcommand10) | Yes | Command to send.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the command is sent, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------- |
| 6600101 | Session service exception. |
| 6600105 | Invalid session command. |
| 6600109 | The remote connection is not established. |
**Example**
```js
let avCommand = {command:'play'};
// let avCommand = {command:'pause'};
// let avCommand = {command:'stop'};
// let avCommand = {command:'playNext'};
// let avCommand = {command:'playPrevious'};
// let avCommand = {command:'fastForward'};
// let avCommand = {command:'rewind'};
// let avCommand = {command:'seek', parameter:10};
aVCastController.sendControlCommand(avCommand, function (err) {
if (err) {
console.error(`SendControlCommand BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`SendControlCommand successfully`);
}
});
```
### prepare10+
prepare(item: AVQueueItem, callback: AsyncCallback\): void
Prepares for the playback of a media asset. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ------------------------------ |
| item | [AVQueueItem](#avqueueitem10) | Yes | Attributes of an item in the playlist.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the command is sent, **err** is **undefined**; otherwise, **err** is an error object.
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
// Set playback parameters.
var playItem = {
itemId: 0,
description: {
mediaId: '12345',
mediaName: 'song1',
mediaType: 'AUDIO',
mediaUri: 'http://resource1_address',
mediaSize: 12345,
startPosition: 0,
duration: 0,
artist: 'mysong',
albumTitle: 'song1_title',
albumCoverUri: "http://resource1_album_address",
lyricUri: "http://resource1_lyric_address",
iconUri: "http://resource1_icon_address",
appName: 'MyMusic'
}
};
// Prepare for playback. This operation triggers loading and buffering, but not the actual playback.
aVCastController.prepare(playItem, () => {
console.info('prepare done');
});
```
### prepare10+
prepare(item: AVQueueItem): Promise\
Prepares for the playback of a media asset. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ------------------------------ |
| item | [AVQueueItem](#avqueueitem10) | Yes | Attributes of an item in the playlist.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the command is sent, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
// Set playback parameters.
var playItem = {
itemId: 0,
description: {
mediaId: '12345',
mediaName: 'song1',
mediaType: 'AUDIO',
mediaUri: 'http://resource1_address',
mediaSize: 12345,
startPosition: 0,
duration: 0,
artist: 'mysong',
albumTitle: 'song1_title',
albumCoverUri: "http://resource1_album_address",
lyricUri: "http://resource1_lyric_address",
iconUri: "http://resource1_icon_address",
appName: 'MyMusic'
}
};
// Prepare for playback. This operation triggers loading and buffering, but not the actual playback.
aVCastController.prepare(playItem, () => {
console.info('prepare done');
});
```
### start10+
start(item: AVQueueItem, callback: AsyncCallback\): void
Prepares for the playback of a media asset. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ------------------------------ |
| item | [AVQueueItem](#avqueueitem10) | Yes | Attributes of an item in the playlist.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the command is sent, **err** is **undefined**; otherwise, **err** is an error object.
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
// Set playback parameters.
var playItem = {
itemId: 0,
description: {
mediaId: '12345',
mediaName: 'song1',
mediaType: 'AUDIO',
mediaUri: 'http://resource1_address',
mediaSize: 12345,
startPosition: 0,
duration: 0,
artist: 'mysong',
albumTitle: 'song1_title',
albumCoverUri: "http://resource1_album_address",
lyricUri: "http://resource1_lyric_address",
iconUri: "http://resource1_icon_address",
appName: 'MyMusic'
}
};
// Start playback.
aVCastController.start(playItem, () => {
console.info('play done');
});
```
### start10+
start(item: AVQueueItem): Promise\
Prepares for the playback of a media asset. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ------------------------------ |
| item | [AVQueueItem](#avqueueitem10) | Yes | Attributes of an item in the playlist.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the command is sent, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
// Set playback parameters.
var playItem = {
itemId: 0,
description: {
mediaId: '12345',
mediaName: 'song1',
mediaType: 'AUDIO',
mediaUri: 'http://resource1_address',
mediaSize: 12345,
startPosition: 0,
duration: 0,
artist: 'mysong',
albumTitle: 'song1_title',
albumCoverUri: "http://resource1_album_address",
lyricUri: "http://resource1_lyric_address",
iconUri: "http://resource1_icon_address",
appName: 'MyMusic'
}
};
// Start playback.
aVCastController.start(playItem).then(() => {
console.info(`start successfully`);
}).catch((err) => {
console.info(`start BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### getCurrentItem10+
getCurrentItem(callback: AsyncCallback\): void
Obtains the information about the media asset that is being played. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| callback | AsyncCallback\<[AVQueueItem](#avqueueitem10)> | Yes | Callback used to return the result. If the command is sent, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
aVCastController.getCurrentItem(function (err, value) {
if (err) {
console.error(`getCurrentItem BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`getCurrentItem successfully`);
}
});
```
### getCurrentItem10+
getCurrentItem(): Promise\
Obtains the information about the media asset that is being played. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\<[AVQueueItem](#avqueueitem10)> | Promise used to return the media asset obtained. If the operation fails, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
**Example**
```js
aVCastController.getCurrentItem().then((AVQueueItem) => {
console.info(`getCurrentItem successfully`);
}).catch((err) => {
console.error(`getCurrentItem BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### on('playbackStateChange')10+
on(type: 'playbackStateChange', filter: Array\ | 'all', callback: (state: AVPlaybackState) => void): void
Subscribes to playback state change events.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'playbackStateChange'** is triggered when the playback state changes.|
| filter | Array\ | 'all' | Yes | The value **'all'** indicates that any playback state field change will trigger the event, and **Array** indicates that only changes to the listed playback state field will trigger the event.|
| callback | (state: [AVPlaybackState](#avplaybackstate10)) => void | Yes | Callback used for subscription. The **state** parameter in the callback indicates the changed playback state. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
**Example**
```js
aVCastController.on('playbackStateChange', 'all', (playbackState) => {
console.info(`on playbackStateChange state : ${playbackState.state}`);
});
let playbackFilter = ['state', 'speed', 'loopMode'];
aVCastController.on('playbackStateChange', playbackFilter, (playbackState) => {
console.info(`on playbackStateChange state : ${playbackState.state}`);
});
```
### off('playbackStateChange')10+
off(type: 'playbackStateChange', callback?: (state: AVPlaybackState) => void): void
Unsubscribes from playback state change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
| type | string | Yes | Event type, which is **'playbackStateChange'** in this case. |
| callback | (state: [AVPlaybackState](#avplaybackstate10)) => void | No | Callback used for unsubscription. The **state** parameter in the callback indicates the changed playback state.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
**Example**
```js
aVCastController.off('playbackStateChange');
```
### on('mediaItemChange')10+
on(type: 'mediaItemChange', callback: Callback\): void
Subscribes to media asset change events.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'mediaItemChange'** is triggered when the media content being played changes.|
| callback | (state: [AVQueueItem](#avqueueitem10)) => void | Yes | Callback used for subscription. **AVQueueItem** is the media asset that is being played. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
**Example**
```js
aVCastController.on('mediaItemChange', (item) => {
console.info(`on mediaItemChange state : ${item.itemId}`);
});
```
### off('mediaItemChange')10+
off(type: 'mediaItemChange'): void
Unsubscribes from media asset change events.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
| type | string | Yes | Event type, which is **'mediaItemChange'** in this case. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
**Example**
```js
aVCastController.off('mediaItemChange');
```
### on('playNext')10+
on(type: 'playNext', callback: Callback\): void
Subscribes to playNext command events.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'playNext'** is triggered when the command for playing the next item is received.|
| callback | Callback\ | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
**Example**
```js
aVCastController.on('playNext', () => {
console.info(`on playNext`);
});
```
### off('playNext')10+
off(type: 'playNext'): void
Unsubscribes from playNext command events.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
| type | string | Yes | Event type, which is **'playNext'** in this case. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
**Example**
```js
aVCastController.off('playNext');
```
### on('playPrevious')10+
on(type: 'playPrevious', callback: Callback\): void
Subscribes to playPrevious command events.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'playPrevious'** is triggered when the command for playing the previous event is received.|
| callback | Callback\ | Yes | Callback used to return the result. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
**Example**
```js
aVCastController.on('playPrevious', () => {
console.info(`on playPrevious`);
});
```
### off('playPrevious')10+
off(type: 'playPrevious'): void
Unsubscribes from the playPrevious command event.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
| type | string | Yes | Event type, which is **'playPrevious'** in this case. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
**Example**
```js
aVCastController.off('playPrevious');
```
### on('seekDone')10+
on(type: 'seekDone', callback: Callback\): void
Subscribes to seek done events.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'seekDone'** is triggered when the seek operation is complete.|
| callback | Callback\ | Yes | Callback used to return the position after the seek operation. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
**Example**
```js
aVCastController.on('seekDone', (pos) => {
console.info(`on seekDone pos: ${pos} `);
});
```
### off('seekDone')10+
off(type: 'seekDone'): void
Unsubscribes from the seek done events.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
| type | string | Yes | Event type, which is **'seekDone'** in this case. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
**Example**
```js
aVCastController.off('seekDone');
```
### on('videoSizeChange')10+
on(type: 'videoSizeChange', callback: (width:number, height:number) => void): void
Subscribes to video size change events.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Parameter | Type | Mandatory | Description |
| type | string | Yes | Event type. The event **'videoSizeChange'** is triggered when the video size changes. |
| callback | (width:number, height:number) => void | Yes | Callback used to return the video width and height. |
**Example**
```js
aVCastController.on('videoSizeChange', (width, height) => {
console.info(`width : ${width} `);
console.info(`height: ${height} `);
});
```
### off('videoSizeChange')10+
off(type: 'videoSizeChange'): void
Unsubscribes from video size changes.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**System API**: This is a system API.
**Parameters**
| Name | Type | Mandatory | Description |
| type | string | Yes | Event type, which is **'videoSizeChange'** in this case. |
**Example**
```js
aVCastController.off('videoSizeChange');
```
### on('error')10+
on(type: 'error', callback: ErrorCallback): void
Subscribes to remote AVPlayer errors. This event is used only for error prompt and does not require the user to stop playback control.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type, which is **'error'** in this case. This event can be triggered by both user operations and the system.|
| callback | function | Yes | Callback used to return the error code ID and error message.|
**Error codes**
For details about the error codes, see [Media Error Codes](../errorcodes/errorcode-media.md).
| ID| Error Message |
| -------- | --------------------- |
| 5400101 | No memory. |
| 5400102 | Operation not allowed. |
| 5400103 | I/O error. |
| 5400104 | Time out. |
| 5400105 | Service died. |
| 5400106 | Unsupport format. |
**Example**
```js
aVCastController.on('error', (error) => {
console.error('error happened,and error message is :' + error.message)
console.error('error happened,and error code is :' + error.code)
})
```
### off('error')10+
off(type: 'error'): void
Unsubscribes from remote AVPlayer errors.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------ | ---- | ----------------------------------------- |
| type | string | Yes | Event type, which is **'error'** in this case.|
**Error codes**
For details about the error codes, see [Media Error Codes](../errorcodes/errorcode-media.md).
| ID| Error Message |
| -------- | --------------------- |
| 5400101 | No memory. |
| 5400102 | Operation not allowed. |
| 5400103 | I/O error. |
| 5400104 | Time out. |
| 5400105 | Service died. |
| 5400106 | Unsupport format. |
**Example**
```js
aVCastController.off('error')
```
## ConnectionState10+
Enumerates the connection states.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Value | Description |
| --------------------------- | ---- | ----------- |
| STATE_CONNECTING | 0 | The device is connecting. |
| STATE_CONNECTED | 1 | The device is connected.|
| STATE_DISCONNECTED | 6 | The device is disconnected.|
## AVMetadata10+
Describes the media metadata.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Type | Mandatory| Description |
| --------------- |-------------------------| ---- |---------------------------------------------------------------------|
| assetId | string | Yes | Media ID. |
| title | string | No | Title. |
| artist | string | No | Artist. |
| author | string | No | Author. |
| album | string | No | Album name. |
| writer | string | No | Writer. |
| composer | string | No | composer. |
| duration | number | No | Media duration, in ms. |
| mediaImage | image.PixelMap | string | No | Pixel map or image path (local path or network path) of the image. |
| publishDate | Date | No | Release date. |
| subtitle | string | No | Subtitle. |
| description | string | No | Media description. |
| lyric | string | No | Lyric file path (local path or network path).|
| previousAssetId | string | No | ID of the previous media asset. |
| nextAssetId | string | No | ID of the next media asset. |
## AVMediaDescription10+
Describes the attributes related to the media metadata in the playlist.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Type | Mandatory | Description |
| ------------ | ----------------------- | ---- | ----------------------- |
| mediaId | string | Yes | Media ID in the playlist. |
| title | string | No | Name of the media asset in the playlist. |
| subtitle | string | No | Subname of the media asset in the playlist. |
| description | string | No | Description of the media asset in the playlist. |
| icon | image.PixelMap | No | Pixel map of the image of the media asset in the playlist.|
| iconUri | string | No | Path of the image of the media asset in the playlist.|
| extras | {[key: string]: any} | No | Additional fields of the media asset in the playlist. |
| mediaUri | string | No | URI of the media asset in the playlist. |
| mediaType | string | No | Type of the media asset in the playlist. |
| mediaSize | number | No | Size of the media asset in the playlist. |
| albumTitle | string | No | Album name of the media asset in the playlist. |
| albumCoverUri | string | No | URI of the album title of the media asset in the playlist. |
| lyricContent | string | No | Lyric content of the media asset in the playlist. |
| lyricUri | string | No | Lyric URI of the media asset in the playlist. |
| artist | string | No | Author of the lyric of the media asset in the playlist. |
| fdSrc | media.AVFileDescriptor | No | Handle to the local media file in the playlist. |
| duration | number | No | Playback duration of the media asset in the playlist. |
| startPosition | number | No | Start position for playing the media asset in the playlist. |
| creditsPosition | number | No | Position for playing the closing credits of the media asset in the playlist. |
| appName | string | No | Name of the application provided by the playlist. |
## AVQueueItem10+
Describes the attributes of an item in the playlist.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Type | Mandatory| Description |
| ------------ | ------------------------------------------ | ---- | --------------------------- |
| itemId | number | Yes | ID of an item in the playlist. |
| description | [AVMediaDescription](#avmediadescription10) | Yes | Media metadata of the item in the playlist. |
## AVPlaybackState10+
Describes the information related to the media playback state.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Type | Mandatory| Description |
| ------------ | ------------------------------------- | ---- | ------- |
| state | [PlaybackState](#playbackstate) | No | Playback state.|
| speed | number | No | Playback speed.|
| position | [PlaybackPosition](#playbackposition) | No | Playback position.|
| bufferedTime | number | No | Buffered time.|
| loopMode | [LoopMode](#loopmode10) | No | Loop mode.|
| isFavorite | boolean | No | Whether the media asset is favorited.|
| activeItemId10+ | number | No | ID of the item that is being played.|
| volume10+ | number | No | Media volume.|
| extras10+ | {[key: string]: Object} | No | Custom media data.|
## PlaybackPosition10+
Describes the information related to the playback position.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Type | Mandatory| Description |
| ----------- | ------ | ---- | ------------------ |
| elapsedTime | number | Yes | Elapsed time, in ms.|
| updateTime | number | Yes | Updated time, in ms.|
## AVCastCategory10+
Enumerates the cast categories.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast
| Name | Value | Description |
| --------------------------- | ---- | ----------- |
| CATEGORY_LOCAL | 0 | Local playback. The sound is played from the local device or a connected Bluetooth headset by default. |
| CATEGORY_REMOTE | 1 | Remote playback. The sound or images are played from a remote device. |
## DeviceType10+
Enumerates the output device types.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Value | Description |
| --------------------------- | ---- | ----------- |
| DEVICE_TYPE_LOCAL | 0 | Local device. |
| DEVICE_TYPE_BLUETOOTH | 10 | Bluetooth device. |
| DEVICE_TYPE_TV | 2 | TV.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast|
| DEVICE_TYPE_SMART_SPEAKER | 3 | Speaker.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast|
## DeviceInfo10+
Describes the information related to the output device.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Type | Mandatory| Description |
| ---------- | -------------- | ---- | ---------------------- |
| castCategory | AVCastCategory | Yes | Cast category. |
| deviceId | string | Yes | ID of the output device. |
| deviceName | string | Yes | Name of the output device. |
| deviceType | DeviceType | Yes | Type of the output device. |
| ipAddress | string | No | IP address of the output device.
This is a system API.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast |
| providerId | number | No | Vendor of the output device.
This is a system API.
**System capability**: SystemCapability.Multimedia.AVSession.AVCast |
## OutputDeviceInfo10+
Describes the information related to the output device.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Type | Mandatory| Description |
| ---------- | -------------- | ---- | ---------------------- |
| devices | Array\ | Yes | Output devices. |
## LoopMode10+
Enumerates the loop modes of media playback.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Value | Description |
| ------------------ | ---- | -------- |
| LOOP_MODE_SEQUENCE | 0 | Sequential playback.|
| LOOP_MODE_SINGLE | 1 | Single loop.|
| LOOP_MODE_LIST | 2 | Playlist loop.|
| LOOP_MODE_SHUFFLE | 3 | Shuffle.|
## PlaybackState10+
Enumerates the media playback states.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Value | Description |
| --------------------------- | ---- | ----------- |
| PLAYBACK_STATE_INITIAL | 0 | Initial. |
| PLAYBACK_STATE_PREPARE | 1 | Preparing. |
| PLAYBACK_STATE_PLAY | 2 | Playing. |
| PLAYBACK_STATE_PAUSE | 3 | Paused. |
| PLAYBACK_STATE_FAST_FORWARD | 4 | Fast-forwarding. |
| PLAYBACK_STATE_REWIND | 5 | Rewinding. |
| PLAYBACK_STATE_STOP | 6 | Stop the playback. |
| PLAYBACK_STATE_COMPLETED | 7 | Playback complete. |
| PLAYBACK_STATE_RELEASED | 8 | Released. |
| PLAYBACK_STATE_ERROR | 9 | Error. |
## AVSessionDescriptor
Declares the session descriptor.
**System capability**: SystemCapability.Multimedia.AVSession.Manager
**System API**: This is a system API.
| Name | Type | Readable| Writable| Description |
| --------------| ---------------- |-----|-----|------|
| sessionId | string | Yes | No| Session ID. |
| type | [AVSessionType](#avsessiontype10) | Yes | No | Session type. |
| sessionTag | string | Yes | No | Custom session name. |
| elementName | [ElementName](js-apis-bundle-ElementName.md) | Yes | No | Information about the application to which the session belongs, including the bundle name and ability name.|
| isActive | boolean | Yes | No | Whether the session is activated. |
| isTopSession | boolean | Yes | No | Whether the session is the top session. |
| outputDevice | [OutputDeviceInfo](#outputdeviceinfo10) | Yes | No | Information about the output device. |
## AVSessionController10+
An AV session controller is created by calling [avSession.createController](#avsessioncreatecontroller). Through the controller, you can query the session ID, send commands and events to a session, and obtain session metadata and playback state information.
### Attributes
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Type | Readable| Writable| Description |
| :-------- | :----- | :--- | :--- | :-------------------------------------- |
| sessionId | string | Yes | No | Unique session ID of the **AVSessionController** object.|
**Example**
```js
let AVSessionController;
avSession.createController(currentAVSession.sessionId).then((controller) => {
AVSessionController = controller;
}).catch((err) => {
console.error(`CreateController BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### getAVPlaybackState10+
getAVPlaybackState(callback: AsyncCallback\): void
Obtains the remote playback state. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| --------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback<[[AVPlaybackState](#avplaybackstate10)\> | Yes | Callback used to return the remote playback state.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getAVPlaybackState(function (err, state) {
if (err) {
console.error(`getAVPlaybackState BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`getAVPlaybackState : SUCCESS`);
}
});
```
### getAVPlaybackState10+
getAVPlaybackState(): Promise\;
Obtains the remote playback state. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| --------- | ------------------------------------------------------------ |
| Promise<[AVPlaybackState](#avplaybackstate10)\> | Promise used to return the remote playback state. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getAVPlaybackState().then((state) => {
console.info(`getAVPlaybackState : SUCCESS :`);
}).catch((err) => {
console.error(`getAVPlaybackState BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### getAVMetadata10+
getAVMetadata(): Promise\
Obtains the session metadata. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| ----------------------------------- | ----------------------------- |
| Promise<[AVMetadata](#avmetadata10)\> | Promise used to return the metadata obtained.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getAVMetadata().then((metadata) => {
console.info(`GetAVMetadata : SUCCESS : assetId : ${metadata.assetId}`);
}).catch((err) => {
console.error(`GetAVMetadata BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### getAVMetadata10+
getAVMetadata(callback: AsyncCallback\): void
Obtains the session metadata. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------- | ---- | -------------------------- |
| callback | AsyncCallback<[AVMetadata](#avmetadata10)\> | Yes | Callback used to return the metadata obtained.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getAVMetadata(function (err, metadata) {
if (err) {
console.error(`GetAVMetadata BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`GetAVMetadata : SUCCESS : assetId : ${metadata.assetId}`);
}
});
```
### getAVQueueTitle10+
getAVQueueTitle(): Promise\
Obtains the name of the playlist. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| ---------------- | ----------------------------- |
| Promise | Promise used to return the playlist name.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getAVQueueTitle().then((title) => {
console.info(`GetAVQueueTitle : SUCCESS : title : ${title}`);
}).catch((err) => {
console.error(`GetAVQueueTitle BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### getAVQueueTitle10+
getAVQueueTitle(callback: AsyncCallback\): void
Obtains the name of the playlist. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------- | ---- | ------------------------- |
| callback | AsyncCallback | Yes | Callback used to return the playlist name.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getAVQueueTitle(function (err, title) {
if (err) {
console.error(`GetAVQueueTitle BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`GetAVQueueTitle : SUCCESS : title : ${title}`);
}
});
```
### getAVQueueItems10+
getAVQueueItems(): Promise\>
Obtains the information related to the items in the queue. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| --------------------------------------------- | ----------------------------- |
| Promise\> | Promise used to return the items in the queue.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getAVQueueItems().then((items) => {
console.info(`GetAVQueueItems : SUCCESS : length : ${items.length}`);
}).catch((err) => {
console.error(`GetAVQueueItems BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### getAVQueueItems10+
getAVQueueItems(callback: AsyncCallback\>): void
Obtains the information related to the items in the playlist. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------------------------------- | ---- | ------------------------- |
| callback | AsyncCallback\> | Yes | Callback used to return the items in the playlist.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getAVQueueItems(function (err, items) {
if (err) {
console.error(`GetAVQueueItems BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`GetAVQueueItems : SUCCESS : length : ${items.length}`);
}
});
```
### skipToQueueItem10+
skipToQueueItem(itemId: number): Promise\
Sends 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.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------ | ------- | ---- | ------------------------------------------- |
| itemId | number | Yes | ID of an item in the playlist.|
**Return value**
| Type | Description |
| -------------- | --------------------------------------------------------------- |
| Promise\ | Promise used to return the result. If the item ID is sent, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
let queueItemId = 0;
avsessionController.skipToQueueItem(queueItemId).then(() => {
console.info(`SkipToQueueItem successfully`);
}).catch((err) => {
console.error(`SkipToQueueItem BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### skipToQueueItem10+
skipToQueueItem(itemId: number, callback: AsyncCallback\): void
Sends 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.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------- | ---- | ----------------------------------------------------------- |
| itemId | number | Yes | ID of an item in the playlist. |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the setting is successful, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
let queueItemId = 0;
avsessionController.skipToQueueItem(queueItemId, function (err) {
if (err) {
console.error(`SkipToQueueItem BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`SkipToQueueItem successfully`);
}
});
```
### getOutputDevice10+
getOutputDevice(): Promise\
Obtains the output device information. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| ----------------------------------------------- | --------------------------------- |
| Promise<[OutputDeviceInfo](#outputdeviceinfo10)\> | Promise used to return the information obtained.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 600101 | Session service exception. |
| 600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getOutputDevice().then((deviceInfo) => {
console.info(`GetOutputDevice : SUCCESS : isRemote : ${deviceInfo.isRemote}`);
}).catch((err) => {
console.error(`GetOutputDevice BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### getOutputDevice10+
getOutputDevice(callback: AsyncCallback\): void
Obtains the output device information. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | ------------------------------ |
| callback | AsyncCallback<[OutputDeviceInfo](#outputdeviceinfo10)\> | Yes | Callback used to return the information obtained.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 600101 | Session service exception. |
| 600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getOutputDevice(function (err, deviceInfo) {
if (err) {
console.error(`GetOutputDevice BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`GetOutputDevice : SUCCESS : isRemote : ${deviceInfo.isRemote}`);
}
});
```
### sendAVKeyEvent10+
sendAVKeyEvent(event: KeyEvent): Promise\
Sends a key event to the session corresponding to this controller. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name| Type | Mandatory| Description |
| ------ | ------------------------------------------------------------ | ---- | ---------- |
| event | [KeyEvent](js-apis-keyevent.md) | Yes | Key event.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 600101 | Session service exception. |
| 600102 | The session does not exist. |
| 600103 | The session controller does not exist. |
| 600105 | Invalid session command. |
| 600106 | The session is not activated. |
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the event is sent, no value is returned; otherwise, an error object is returned.|
**Example**
```js
let keyItem = {code:0x49, pressedTime:2, deviceId:0};
let event = {action:2, key:keyItem, keys:[keyItem]};
avsessionController.sendAVKeyEvent(event).then(() => {
console.info(`SendAVKeyEvent Successfully`);
}).catch((err) => {
console.error(`SendAVKeyEvent BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### sendAVKeyEvent10+
sendAVKeyEvent(event: KeyEvent, callback: AsyncCallback\): void
Sends a key event to the session corresponding to this controller. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ---------- |
| event | [KeyEvent](js-apis-keyevent.md) | Yes | Key event.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the event is sent, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 600101 | Session service exception. |
| 600102 | The session does not exist. |
| 600103 | The session controller does not exist. |
| 600105 | Invalid session command. |
| 600106 | The session is not activated. |
**Example**
```js
let keyItem = {code:0x49, pressedTime:2, deviceId:0};
let event = {action:2, key:keyItem, keys:[keyItem]};
avsessionController.sendAVKeyEvent(event, function (err) {
if (err) {
console.error(`SendAVKeyEvent BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`SendAVKeyEvent Successfully`);
}
});
```
### getLaunchAbility10+
getLaunchAbility(): Promise\
Obtains the **WantAgent** object saved by the application in the session. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| ------------------------------------------------------- | ------------------------------------------------------------ |
| Promise<[WantAgent](js-apis-app-ability-wantAgent.md)\> | Promise used to return the object saved by calling [setLaunchAbility](#setlaunchability10). The object includes the application attribute, such as the bundle name, ability name, and device ID.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getLaunchAbility().then((agent) => {
console.info(`GetLaunchAbility : SUCCESS : wantAgent : ${agent}`);
}).catch((err) => {
console.error(`GetLaunchAbility BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### getLaunchAbility10+
getLaunchAbility(callback: AsyncCallback\): void
Obtains the **WantAgent** object saved by the application in the session. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback<[WantAgent](js-apis-app-ability-wantAgent.md)\> | Yes | Callback used to return the object saved by calling [setLaunchAbility](#setlaunchability10). The object includes the application attribute, such as the bundle name, ability name, and device ID.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getLaunchAbility(function (err, agent) {
if (err) {
console.error(`GetLaunchAbility BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`GetLaunchAbility : SUCCESS : wantAgent : ${agent}`);
}
});
```
### getRealPlaybackPositionSync10+
getRealPlaybackPositionSync(): number
Obtains the playback position.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| ------ | ------------------ |
| number | Playback position, in milliseconds.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
let time = avsessionController.getRealPlaybackPositionSync();
```
### isActive10+
isActive(): Promise\
Checks whether the session is activated. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| ----------------- | ------------------------------------------------------------ |
| Promise | Promise used to return the activation state. If the session is activated, **true** is returned; otherwise, **false** is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.isActive().then((isActive) => {
console.info(`IsActive : SUCCESS : isactive : ${isActive}`);
}).catch((err) => {
console.error(`IsActive BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### isActive10+
isActive(callback: AsyncCallback\): void
Checks whether the session is activated. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback | Yes | Callback used to return the activation state. If the session is activated, **true** is returned; otherwise, **false** is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.isActive(function (err, isActive) {
if (err) {
console.error(`IsActive BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`IsActive : SUCCESS : isactive : ${isActive}`);
}
});
```
### destroy10+
destroy(): Promise\
Destroys this controller. A controller can no longer be used after being destroyed. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the controller is destroyed, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.destroy().then(() => {
console.info(`Destroy : SUCCESS `);
}).catch((err) => {
console.error(`Destroy BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### destroy10+
destroy(callback: AsyncCallback\): void
Destroys this controller. A controller can no longer be used after being destroyed. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | -------------------- | ---- | ---------- |
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the controller is destroyed, **err** is **undefined**; otherwise, **err** is an error object.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.destroy(function (err) {
if (err) {
console.error(`Destroy BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`Destroy : SUCCESS `);
}
});
```
### getValidCommands10+
getValidCommands(): Promise\>
Obtains valid commands supported by the session. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| ------------------------------------------------------------ | --------------------------------- |
| Promise\> | Promise used to return a set of valid commands.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getValidCommands.then((validCommands) => {
console.info(`GetValidCommands : SUCCESS : size : ${validCommands.length}`);
}).catch((err) => {
console.error(`GetValidCommands BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### getValidCommands10+
getValidCommands(callback: AsyncCallback\>): void
Obtains valid commands supported by the session. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------ |
| callback | AsyncCallback\\> | Yes | Callback used to return a set of valid commands.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.getValidCommands(function (err, validCommands) {
if (err) {
console.error(`GetValidCommands BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`GetValidCommands : SUCCESS : size : ${validCommands.length}`);
}
});
```
### sendControlCommand10+
sendControlCommand(command: AVControlCommand): Promise\
Sends a control command to the session through the controller. This API uses a promise to return the result.
> **NOTE**
>
> 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'](#onplay10), [on'pause'](#onpause10), and the like.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ------------------------------ |
| command | [AVControlCommand](#avcontrolcommand10) | Yes | Command to send.|
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the command is sent, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
| 6600105 | Invalid session command. |
| 6600106 | The session is not activated. |
| 6600107 | Too many commands or events. |
**Example**
```js
let avCommand = {command:'play'};
// let avCommand = {command:'pause'};
// let avCommand = {command:'stop'};
// let avCommand = {command:'playNext'};
// let avCommand = {command:'playPrevious'};
// let avCommand = {command:'fastForward'};
// let avCommand = {command:'rewind'};
// let avCommand = {command:'seek', parameter:10};
// let avCommand = {command:'setSpeed', parameter:2.6};
// let avCommand = {command:'setLoopMode', parameter:avSession.LoopMode.LOOP_MODE_SINGLE};
// let avCommand = {command:'toggleFavorite', parameter:"false"};
avsessionController.sendControlCommand(avCommand).then(() => {
console.info(`SendControlCommand successfully`);
}).catch((err) => {
console.error(`SendControlCommand BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### sendControlCommand10+
sendControlCommand(command: AVControlCommand, callback: AsyncCallback\): void
Sends a control command to the session through the controller. This API uses an asynchronous callback to return the result.
> **NOTE**
>
> 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'](#onplay10), [on'pause'](#onpause10), and the like.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------- | ---- | ------------------------------ |
| command | [AVControlCommand](#avcontrolcommand10) | Yes | Command to send.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the command is sent, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
| 6600105 | Invalid session command. |
| 6600106 | The session is not activated. |
| 6600107 | Too many commands or events. |
**Example**
```js
let avCommand = {command:'play'};
// let avCommand = {command:'pause'};
// let avCommand = {command:'stop'};
// let avCommand = {command:'playNext'};
// let avCommand = {command:'playPrevious'};
// let avCommand = {command:'fastForward'};
// let avCommand = {command:'rewind'};
// let avCommand = {command:'seek', parameter:10};
// let avCommand = {command:'setSpeed', parameter:2.6};
// let avCommand = {command:'setLoopMode', parameter:avSession.LoopMode.LOOP_MODE_SINGLE};
// let avCommand = {command:'toggleFavorite', parameter:"false"};
avsessionController.sendControlCommand(avCommand, function (err) {
if (err) {
console.info(`SendControlCommand BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.error(`SendControlCommand successfully`);
}
});
```
### sendCommonCommand10+
sendCommonCommand(command: string, args: {[key: string]: Object}): Promise\
Sends a custom control command to the session through the controller. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ------------------------------ |
| command | string | Yes | Name of the custom control command.|
| args | {[key: string]: any} | Yes | Parameters in key-value pair format carried in the custom control command.|
> **NOTE**
> The **args** parameter supports the following data types: string, number, Boolean, object, array, and file descriptor. For details, see [@ohos.app.ability.Want (Want)](./js-apis-app-ability-want.md).
**Return value**
| Type | Description |
| -------------- | ----------------------------- |
| Promise\ | Promise used to return the result. If the command is sent, no value is returned; otherwise, an error object is returned.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
| 6600105 | Invalid session command. |
| 6600106 | The session is not activated. |
| 6600107 | Too many commands or events. |
**Example**
```js
let commandName = "my_command";
let args = {
command : "This is my command"
}
avsessionController.sendCommonCommand(commandName, args).catch((err) => {
console.info(`SendCommonCommand BusinessError: code: ${err.code}, message: ${err.message}`);
})
```
### sendCommonCommand10+
sendCommonCommand(command: string, args: {[key: string]: Object}, callback: AsyncCallback\): void
Sends a custom control command to the session through the controller. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| ------- | ------------------------------------- | ---- | ------------------------------ |
| command | string | Yes | Name of the custom control command.|
| args | {[key: string]: any} | Yes | Parameters in key-value pair format carried in the custom control command.|
| callback | AsyncCallback\ | Yes | Callback used to return the result. If the command is sent, **err** is **undefined**; otherwise, **err** is an error object. |
> **NOTE**
> The **args** parameter supports the following data types: string, number, Boolean, object, array, and file descriptor. For details, see [@ohos.app.ability.Want (Want)](./js-apis-app-ability-want.md).
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
| 6600105 | Invalid session command. |
| 6600106 | The session is not activated. |
| 6600107 | Too many commands or events. |
**Example**
```js
let commandName = "my_command";
let args = {
command : "This is my command"
}
avsessionController.sendCommonCommand(commandName, args, (err) => {
if(err) {
console.info(`SendCommonCommand BusinessError: code: ${err.code}, message: ${err.message}`);
}
})
```
### getExtras10+
getExtras(): Promise\<{[key: string]: Object}>
Obtains the custom media packet set by the provider. This API uses a promise to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Return value**
| Type | Description |
| ----------------------------------- | ----------------------------- |
| 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**.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
| 6600105 | Invalid session command. |
| 6600107 | Too many commands or events. |
**Example**
```js
let extras = await avsessionController.getExtras().catch((err) => {
console.info(`getExtras BusinessError: code: ${err.code}, message: ${err.message}`);
});
```
### getExtras10+
getExtras(callback: AsyncCallback\<{[key: string]: Object}>): void
Obtains the custom media packet set by the provider. This API uses an asynchronous callback to return the result.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------- | ---- | -------------------------- |
| 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**.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------------------------------- |
| 6600101 | Session service exception. |
| 6600102 | The session does not exist. |
| 6600103 | The session controller does not exist. |
| 6600105 | Invalid session command. |
| 6600107 | Too many commands or events. |
**Example**
```js
avsessionController.getExtras(function (err, extras) {
if (err) {
console.error(`getExtras BusinessError: code: ${err.code}, message: ${err.message}`);
} else {
console.info(`getExtras : SUCCESS : assetId : ${extras}`);
}
});
```
### on('metadataChange')10+
on(type: 'metadataChange', filter: Array\ | 'all', callback: (data: AVMetadata) => void)
Subscribes to metadata change events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'metadataChange'** is triggered when the session metadata changes.|
| filter | Array\ | 'all' | Yes | The value **'all'** indicates that any metadata field change will trigger the event, and **Array** indicates that only changes to the listed metadata field will trigger the event.|
| callback | (data: [AVMetadata](#avmetadata10)) => void | Yes | Callback used for subscription. The **data** parameter in the callback indicates the changed metadata. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.on('metadataChange', 'all', (metadata) => {
console.info(`on metadataChange assetId : ${metadata.assetId}`);
});
let metaFilter = ['assetId', 'title', 'description'];
avsessionController.on('metadataChange', metaFilter, (metadata) => {
console.info(`on metadataChange assetId : ${metadata.assetId}`);
});
```
### off('metadataChange')10+
off(type: 'metadataChange', callback?: (data: AVMetadata) => void)
Unsubscribes from metadata change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------ |
| type | string | Yes | Event type, which is **'metadataChange'** in this case. |
| callback | (data: [AVMetadata](#avmetadata10)) => void | No | Callback used for subscription. The **data** parameter in the callback indicates the changed metadata.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.off('metadataChange');
```
### on('playbackStateChange')10+
on(type: 'playbackStateChange', filter: Array\ | 'all', callback: (state: AVPlaybackState) => void)
Subscribes to playback state change events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| --------| -----------|-----|------------|
| type | string | Yes | Event type. The event **'playbackStateChange'** is triggered when the playback state changes.|
| filter | Array\ | 'all' | Yes | The value **'all'** indicates that any playback state field change will trigger the event, and **Array** indicates that only changes to the listed playback state field will trigger the event.|
| callback | (state: [AVPlaybackState](#avplaybackstate10)) => void | Yes | Callback used for subscription. The **state** parameter in the callback indicates the changed playback state.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.on('playbackStateChange', 'all', (playbackState) => {
console.info(`on playbackStateChange state : ${playbackState.state}`);
});
let playbackFilter = ['state', 'speed', 'loopMode'];
avsessionController.on('playbackStateChange', playbackFilter, (playbackState) => {
console.info(`on playbackStateChange state : ${playbackState.state}`);
});
```
### off('playbackStateChange')10+
off(type: 'playbackStateChange', callback?: (state: AVPlaybackState) => void)
Unsubscribes from playback state change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
| type | string | Yes | Event type, which is **'playbackStateChange'** in this case. |
| callback | (state: [AVPlaybackState](#avplaybackstate10)) => void | No | Callback used for unsubscription. The **state** parameter in the callback indicates the changed playback state.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.off('playbackStateChange');
```
### on('sessionDestroy')10+
on(type: 'sessionDestroy', callback: () => void)
Subscribes to session destruction events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'sessionDestroy'** is triggered when a session is destroyed.|
| callback | () => void | Yes | Callback used for subscription. If the subscription is successful, **err** is **undefined**; otherwise, **err** is an error object. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.on('sessionDestroy', () => {
console.info(`on sessionDestroy : SUCCESS `);
});
```
### off('sessionDestroy')10+
off(type: 'sessionDestroy', callback?: () => void)
Unsubscribes from session destruction events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------- | ---- | ----------------------------------------------------- |
| type | string | Yes | Event type, which is **'sessionDestroy'** in this case. |
| callback | () => void | No | Callback used for unsubscription. If the unsubscription is successful, **err** is **undefined**; otherwise, **err** is an error object.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.off('sessionDestroy');
```
### on('activeStateChange')10+
on(type: 'activeStateChange', callback: (isActive: boolean) => void)
Subscribes to session activation state change events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'activeStateChange'** is triggered when the activation state of the session changes.|
| 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. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ----------------------------- |
| 6600101 | Session service exception. |
| 6600103 |The session controller does not exist. |
**Example**
```js
avsessionController.on('activeStateChange', (isActive) => {
console.info(`on activeStateChange : SUCCESS : isActive ${isActive}`);
});
```
### off('activeStateChange')10+
off(type: 'activeStateChange', callback?: (isActive: boolean) => void)
Unsubscribes from session activation state change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | --------------------------- | ---- | ----------------------------------------------------- |
| type | string | Yes | Event type, which is **'activeStateChange'** in this case. |
| 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.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.off('activeStateChange');
```
### on('validCommandChange')10+
on(type: 'validCommandChange', callback: (commands: Array\) => void)
Subscribes to valid command change events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'validCommandChange'** is triggered when the valid commands supported by the session changes.|
| callback | (commands: Array<[AVControlCommandType](#avcontrolcommandtype10)\>) => void | Yes | Callback used for subscription. The **commands** parameter in the callback is a set of valid commands. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.on('validCommandChange', (validCommands) => {
console.info(`validCommandChange : SUCCESS : size : ${validCommands.size}`);
console.info(`validCommandChange : SUCCESS : validCommands : ${validCommands.values()}`);
});
```
### off('validCommandChange')10+
off(type: 'validCommandChange', callback?: (commands: Array\) => void)
Unsubscribes from valid command change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- |
| type | string | Yes | Event type, which is **'validCommandChange'** in this case. |
| callback | (commands: Array<[AVControlCommandType](#avcontrolcommandtype10)\>) => void | No | Callback used for unsubscription. The **commands** parameter in the callback is a set of valid commands.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message |
| -------- | ---------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.off('validCommandChange');
```
### on('outputDeviceChange')10+
on(type: 'outputDeviceChange', callback: (state: ConnectionState, device: OutputDeviceInfo) => void): void
Subscribes to output device change events.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'outputDeviceChange'** is triggered when the output device changes.|
| callback | (state: [ConnectionState](#connectionstate10), device: [OutputDeviceInfo](#outputdeviceinfo10)) => void | Yes | Callback used for subscription. The **device** parameter in the callback indicates the output device information. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ----------------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.on('outputDeviceChange', (state, device) => {
console.info(`on outputDeviceChange state: ${state}, device : ${device}`);
});
```
### off('outputDeviceChange')10+
off(type: 'outputDeviceChange', callback?: (state: ConnectionState, device: OutputDeviceInfo) => void): void
Unsubscribes from output device change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------ |
| type | string | Yes | Event type, which is **'outputDeviceChange'** in this case. |
| callback | (state: [ConnectionState](#connectionstate10), device: [OutputDeviceInfo](#outputdeviceinfo10)) => void | No | Callback used for unsubscription. The **device** parameter in the callback indicates the output device information.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID | Error Message |
| -------- | ---------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.off('outputDeviceChange');
```
### on('sessionEvent')10+
on(type: 'sessionEvent', callback: (sessionEvent: string, args: {[key:string]: Object}) => void): void
Subscribes to session event change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'sessionEvent'** is triggered when the session event changes.|
| 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. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.on('sessionEvent', (sessionEvent, args) => {
console.info(`OnSessionEvent, sessionEvent is ${sessionEvent}, args: ${JSON.stringify(args)}`);
});
```
### off('sessionEvent')10+
off(type: 'sessionEvent', callback?: (sessionEvent: string, args: {[key:string]: Object}) => void): void
Unsubscribes from session event change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
| type | string | Yes | Event type, which is **'sessionEvent'** in this case. |
| 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.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.off('sessionEvent');
```
### on('queueItemsChange')10+
on(type: 'queueItemsChange', callback: (items: Array<[AVQueueItem](#avqueueitem10)\>) => void): void
Subscribes to playlist item change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------------------------------------- | ---- | ---------------------------------------------------------------------------- |
| type | string | Yes | Event type. The event **'queueItemsChange'** is triggered when one or more items in the playlist changes.|
| callback | (items: Array<[AVQueueItem](#avqueueitem10)\>) => void | Yes | Callback used for subscription. The **items** parameter in the callback indicates the changed items in the playlist. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.on('queueItemsChange', (items) => {
console.info(`OnQueueItemsChange, items length is ${items.length}`);
});
```
### off('queueItemsChange')10+
off(type: 'queueItemsChange', callback?: (items: Array<[AVQueueItem](#avqueueitem10)\>) => void): void
Unsubscribes from playback item change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ---------------------------------------------------- | ---- | --------------------------------------------------------------------------------------------------- |
| type | string | Yes | Event type, which is **'queueItemsChange'** in this case. |
| callback | (items: Array<[AVQueueItem](#avqueueitem10)\>) => void | No | Callback used for unsubscription. The **items** parameter in the callback indicates the changed items in the playlist.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.off('queueItemsChange');
```
### on('queueTitleChange')10+
on(type: 'queueTitleChange', callback: (title: string) => void): void
Subscribes to playlist name change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------- | ---- | ------------------------------------------------------------------------------- |
| type | string | Yes | Event type. The event **'queueTitleChange'** is triggered when the playlist name changes.|
| callback | (title: string) => void | Yes | Callback used for subscription. The **title** parameter in the callback indicates the changed playlist name. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.on('queueTitleChange', (title) => {
console.info(`queueTitleChange, title is ${title}`);
});
```
### off('queueTitleChange')10+
off(type: 'queueTitleChange', callback?: (title: string) => void): void
Unsubscribes from playlist name change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------- | ---- | ------------------------------------------------------------------------------------------------------- |
| type | string | Yes | Event type, which is **'queueTitleChange'** in this case. |
| callback | (title: string) => void | No | Callback used for unsubscription. The **items** parameter in the callback indicates the changed playlist name.
The **callback** parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.off('queueTitleChange');
```
### on('extrasChange')10+
on(type: 'extrasChange', callback: (extras: {[key:string]: Object}) => void): void
Subscribes to custom media packet change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | Yes | Event type. The event **'extrasChange'** is triggered when the provider sets a custom media packet.|
| 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**. |
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ------------------------------ |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.on('extrasChange', (extras) => {
console.info(`Caught extrasChange event,the new extra is: ${JSON.stringify(extras)}`);
});
```
### off('extrasChange')10+
off(type: 'extrasChange', callback?: (extras: {[key:string]: Object}) => void): void
Unsubscribes from custom media packet change events. This API is called by the controller.
**System capability**: SystemCapability.Multimedia.AVSession.Core
**Parameters**
| Name | Type | Mandatory| Description |
| -------- | ----------------------- | ---- | ------------------------------------------------------------------------------------------------------- |
| type | string | Yes | Event type, which is **'extrasChange'** in this case. |
| callback | ({[key:string]: Object}) => void | 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.|
**Error codes**
For details about the error codes, see [AVSession Management Error Codes](../errorcodes/errorcode-avsession.md).
| ID| Error Message|
| -------- | ---------------- |
| 6600101 | Session service exception. |
| 6600103 | The session controller does not exist. |
**Example**
```js
avsessionController.off('extrasChange');
```
## AVControlCommandType10+
Enumerates the commands that can be sent to a session.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Type | Description |
| -------------- | ------ | ------------ |
| play | string | Play the media. |
| pause | string | Pause the playback. |
| stop | string | Stop the playback. |
| playNext | string | Play the next media asset. |
| playPrevious | string | Play the previous media asset. |
| fastForward | string | Fast-forward. |
| rewind | string | Rewind. |
| seek | string | Seek to a playback position.|
| setSpeed | string | Set the playback speed.|
| setLoopMode | string | Set the loop mode.|
| toggleFavorite | string | Favorite the media asset. |
## AVControlCommand10+
Describes the command that can be sent to the session.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Type | Mandatory| Description |
| --------- | ------------------------------------------------- | ---- | -------------- |
| command | [AVControlCommandType](#avcontrolcommandtype10) | Yes | Command. |
| parameter | [LoopMode](#loopmode10) | string | number | No | Parameters carried in the command.|
## AVSessionErrorCode10+
Enumerates the error codes used in the media session.
**System capability**: SystemCapability.Multimedia.AVSession.Core
| Name | Value | Description |
| -------------------------------------- | ------- | ------------------------------- |
| ERR_CODE_SERVICE_EXCEPTION | 6600101 | Session service exception. |
| ERR_CODE_SESSION_NOT_EXIST | 6600102 | The session does not exist. |
| ERR_CODE_CONTROLLER_NOT_EXIST | 6600103 | The session controller does not exist. |
| ERR_CODE_REMOTE_CONNECTION_ERR | 6600104 | The remote session connection failed. |
| ERR_CODE_COMMAND_INVALID | 6600105 | Invalid session command. |
| ERR_CODE_SESSION_INACTIVE | 6600106 | The session is not activated. |
| ERR_CODE_MESSAGE_OVERLOAD | 6600107 | Too many commands or events. |
| ERR_CODE_DEVICE_CONNECTION_FAILED | 6600108 | Device connecting failed. |
| ERR_CODE_REMOTE_CONNECTION_NOT_EXIST | 6600109 | The remote connection is not established. |