Interface (AVSession)

An AVSession object is created by calling avSession.createAVSession. The object enables you to obtain the session ID and set the metadata and playback state.

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.

The initial APIs of this interface are supported since API version 10.

Modules to Import

import { avSession } from '@kit.AVSessionKit';

Properties

System capability: SystemCapability.Multimedia.AVSession.Core

Name	Type	Read-Only	Optional	Description
sessionId¹⁰⁺	string	Yes	No	Unique session ID of the AVSession object. Atomic service API: This API can be used in atomic services since API version 12.
sessionType¹⁰⁺	AVSessionType	Yes	No	AVSession type. Atomic service API: This API can be used in atomic services since API version 12.
sessionTag²²⁺	string	Yes	No	Custom tag information of the AVSession. Atomic service API: This API can be used in atomic services since API version 22.

Example

let sessionId: string = currentAVSession.sessionId;
let sessionType: avSession.AVSessionType = currentAVSession.sessionType;

setAVMetadata¹⁰⁺

setAVMetadata(data: AVMetadata): Promise<void>

Sets session metadata. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
data	AVMetadata	Yes	Session metadata.

Return value

Type	Description
Promise<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example



let metadata: avSession.AVMetadata = {
  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",
  // The LRC contains two types of elements: time tag + lyrics, and ID tag.
  // Example: [00:25.44]xxx\r\n[00:26.44]xxx\r\n
  lyric: "Lyrics in LRC format",
  // The singleLyricText field stores a single line of lyric text without timestamps.
  // Example: "Content of a single lyric line"
  singleLyricText: "Content of a single lyric line",
  previousAssetId: "121277",
  nextAssetId: "121279"
};
currentAVSession.setAVMetadata(metadata).then(() => {
  console.info('Succeeded in setting AVMetadata.');
});

setAVMetadata¹⁰⁺

setAVMetadata(data: AVMetadata, callback: AsyncCallback<void>): 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	Yes	Session metadata.
callback	AsyncCallback<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example



let metadata: avSession.AVMetadata = {
  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",
  // The LRC contains two types of elements: time tag + lyrics, and ID tag.
  // Example: [00:25.44]xxx\r\n[00:26.44]xxx\r\n
  lyric: "Lyrics in LRC format",
  // The singleLyricText field stores a single line of lyric text without timestamps.
  // Example: "Content of a single lyric line"
  singleLyricText: "Content of a single lyric line",
  previousAssetId: "121277",
  nextAssetId: "121279"
};
currentAVSession.setAVMetadata(metadata, () => {
  console.info('Succeeded in setting AVMetadata.');
});

setCallMetadata¹¹⁺

setCallMetadata(data: CallMetadata): Promise<void>

Sets call metadata. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
data	CallMetadata	Yes	Call metadata.

Return value

Type	Description
Promise<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example

import { image } from '@kit.ImageKit';
import { resourceManager } from '@kit.LocalizationKit';

import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  build() {
    Column() {
      Text('Hello World')
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
    }
    .width('100%')
    .height('100%')
  }
}

class CallManager {
  private currentAVSession: avSession.AVSession | null = null;

  async setCallMetadata() {
    try {
      let value = await resourceManager.getSysResourceManager().getRawFileContent('IMAGE_URI');
      let imageSource = await image.createImageSource(value.buffer);
      let imagePixel = await imageSource.createPixelMap({ desiredSize: { width: 150, height: 150 } });
      let calldata: avSession.CallMetadata = {
        name: "xiaoming",
        phoneNumber: "111xxxxxxxx",
        avatar: imagePixel
      };
      await this.currentAVSession?.setCallMetadata(calldata);
      console.info('Succeeded in setting call metadata.');
    }
  }
}

setCallMetadata¹¹⁺

setCallMetadata(data: CallMetadata, callback: AsyncCallback<void>): void

Sets call metadata. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
data	CallMetadata	Yes	Call metadata.
callback	AsyncCallback<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example

import { image } from '@kit.ImageKit';
import { resourceManager } from '@kit.LocalizationKit';

import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  build() {
    Column() {
      Text('Hello World')
        .fontSize(50)
        .fontWeight(FontWeight.Bold)
    }
    .width('100%')
    .height('100%')
  }
}

class CallManager {
  private currentAVSession: avSession.AVSession | null = null;

  async setCallMetadata() {
    try {
      let value = await resourceManager.getSysResourceManager().getRawFileContent('IMAGE_URI');
      let imageSource = await image.createImageSource(value.buffer);
      let imagePixel = await imageSource.createPixelMap({ desiredSize: { width: 150, height: 150 } });
      let calldata: avSession.CallMetadata = {
        name: "xiaoming",
        phoneNumber: "111xxxxxxxx",
        avatar: imagePixel
      };
      this.currentAVSession?.setCallMetadata(calldata, () => {
        console.info('Succeeded in setting call metadata.');
      });
    }
  }
}

setAVCallState¹¹⁺

setAVCallState(state: AVCallState): Promise<void>

Sets the call state. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
state	AVCallState	Yes	Call state.

Return value

Type	Description
Promise<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example



let calldata: avSession.AVCallState = {
  state: avSession.CallState.CALL_STATE_ACTIVE,
  muted: false
};
currentAVSession.setAVCallState(calldata).then(() => {
  console.info('Succeeded in setting AVCallState.');
});

setAVCallState¹¹⁺

setAVCallState(state: AVCallState, callback: AsyncCallback<void>): void

Sets the call state. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
state	AVCallState	Yes	Call state.
callback	AsyncCallback<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example



let avcalldata: avSession.AVCallState = {
  state: avSession.CallState.CALL_STATE_ACTIVE,
  muted: false
};
currentAVSession.setAVCallState(avcalldata, () => {
  console.info('Succeeded in setting AVCallState.');
});

setAVPlaybackState¹⁰⁺

setAVPlaybackState(state: AVPlaybackState): Promise<void>

Sets information related to the session playback state. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
state	AVPlaybackState	Yes	Information related to the session playback state.

Return value

Type	Description
Promise<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example



let playbackState: avSession.AVPlaybackState = {
  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('Succeeded in setting AVPlaybackState.');
});

setAVPlaybackState¹⁰⁺

setAVPlaybackState(state: AVPlaybackState, callback: AsyncCallback<void>): 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
state	AVPlaybackState	Yes	Information related to the session playback state.
callback	AsyncCallback<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example



let PlaybackState: avSession.AVPlaybackState = {
  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, () => {
  console.info('Succeeded in setting AVPlaybackState.');
});

setLaunchAbility¹⁰⁺

setLaunchAbility(ability: WantAgent): Promise<void>

Sets a launcher ability. This API uses a promise to return the result.

The user can tap the playback control component to go to the corresponding playback screen. By default, the UIAbility screen to which the context passed by the avSession.createAVSession API belongs is displayed.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
ability	WantAgent	Yes	Application properties, such as the bundle name, ability name, and deviceID.

Return value

Type	Description
Promise<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example

import { wantAgent } from '@kit.AbilityKit';


// WantAgentInfo object.
let wantAgentInfo: wantAgent.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('Succeeded in setting launch ability.');
  });
});

setLaunchAbility¹⁰⁺

setLaunchAbility(ability: WantAgent, callback: AsyncCallback<void>): 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	Yes	Application properties, such as the bundle name, ability name, and deviceID.
callback	AsyncCallback<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example

import { wantAgent } from '@kit.AbilityKit';


// WantAgentInfo object.
let wantAgentInfo: wantAgent.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, () => {
    console.info('Succeeded in setting launch ability.');
  });
});

dispatchSessionEvent¹⁰⁺

dispatchSessionEvent(event: string, args: {[key: string]: Object}): Promise<void>

Dispatches a custom event in the session, including the event name and event content in key-value pair format. This API is called by the provider. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Name of the session event.
args	{[key: string]: Object}	Yes	Content of the session event.

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).

Return value

Type	Description
Promise<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example


import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() { 
    Column() {
        Text(this.message)
          .onClick(()=>{
            let currentAVSession: avSession.AVSession | undefined = undefined;
            let tag = "createNewSession";
            let context: Context = this.getUIContext().getHostContext() as Context;

            avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
              currentAVSession = data;
              let eventName = "dynamic_lyric";
              if (currentAVSession !== undefined) {
                (currentAVSession as avSession.AVSession).dispatchSessionEvent(eventName, {lyric : "This is lyric"}).then(() => {
                  console.info('Succeeded in dispatching session event.');
                })
              }
            });
          })
      }
    .width('100%')
    .height('100%')
  }
}

dispatchSessionEvent¹⁰⁺

dispatchSessionEvent(event: string, args: {[key: string]: Object}, callback: AsyncCallback<void>): void

Dispatches a custom event in the session, including the event name and event content in key-value pair format. This API is called by the provider. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Name of the session event.
args	{[key: string]: Object}	Yes	Content of the session event.
callback	AsyncCallback<void>	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).

Error codes

For details about the error codes, see Universal Error Codes and AVSession Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types. 3.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example


import { avSession } from '@kit.AVSessionKit';
@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() { 
    Column() {
        Text(this.message)
          .onClick(()=>{
            let currentAVSession: avSession.AVSession | undefined = undefined;
            let tag = "createNewSession";
            let context: Context = this.getUIContext().getHostContext() as Context;

            avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
              currentAVSession = data;
              let eventName: string = "dynamic_lyric";
              if (currentAVSession !== undefined) {
                (currentAVSession as avSession.AVSession).dispatchSessionEvent(eventName, {lyric : "This is lyric"}, () => {
                  console.info('Succeeded in dispatching session event.');
                })
              }
            });
          })
      }
    .width('100%')
    .height('100%')
  }
}

setAVQueueItems¹⁰⁺

setAVQueueItems(items: Array<AVQueueItem>): Promise<void>

Sets a playlist. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
items	Array<AVQueueItem>	Yes	Playlist to set.

Return value

Type	Description
Promise<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example

import { image } from '@kit.ImageKit';
import { resourceManager } from '@kit.LocalizationKit';

import { avSession } from '@kit.AVSessionKit';
interface ExtrasType {
  extras: string;
}

@Entry
@Component
struct Index {
  build() {
    Column() {
    }
  }
}

let currentAVSession: avSession.AVSession;

async function setAVQueueItems() {
  try {
    let value = await resourceManager.getSysResourceManager().getRawFileContent('IMAGE_URI');
    let imageSource = await image.createImageSource(value.buffer);
    let imagePixel = await imageSource.createPixelMap({desiredSize:{width: 150, height: 150}});
    let queueItemDescription_1: avSession.AVMediaDescription = {
      assetId: '001',
      title: 'music_name',
      subtitle: 'music_sub_name',
      description: 'music_description',
      mediaImage : imagePixel,
      extras: {extras:'any'}
    };
    let queueItem_1: avSession.AVQueueItem = {
      itemId: 1,
      description: queueItemDescription_1
    } as avSession.AVQueueItem;
    let queueItemDescription_2: avSession.AVMediaDescription = {
      assetId: '002',
      title: 'music_name',
      subtitle: 'music_sub_name',
      description: 'music_description',
      mediaImage: imagePixel,
      extras: {extras:'any'}
    };
    let queueItem_2: avSession.AVQueueItem = {
      itemId: 2,
      description: queueItemDescription_2
    } as avSession.AVQueueItem;
    let queueItemsArray: avSession.AVQueueItem[] = [queueItem_1, queueItem_2];
    currentAVSession.setAVQueueItems(queueItemsArray).then(() => {
      console.info('Succeeded in setting AVQueueItems.');
    });
  }
}

setAVQueueItems¹⁰⁺

setAVQueueItems(items: Array<AVQueueItem>, callback: AsyncCallback<void>): 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>	Yes	Playlist to set.
callback	AsyncCallback<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example

import { image } from '@kit.ImageKit';
import { resourceManager } from '@kit.LocalizationKit';

import { avSession } from '@kit.AVSessionKit'

interface ExtrasType {
  extras: string;
}

@Entry
@Component
struct Index {
  build() {
    Column() {
    }
  }
}

let currentAVSession: avSession.AVSession;

async function setAVQueueItems() {
  try {
    let value = await resourceManager.getSysResourceManager().getRawFileContent('IMAGE_URI');
    let imageSource = await image.createImageSource(value.buffer);
    let imagePixel = await imageSource.createPixelMap({ desiredSize: { width: 150, height: 150 } });
    let queueItemDescription_1: avSession.AVMediaDescription = {
      assetId: '001',
      title: 'music_name',
      subtitle: 'music_sub_name',
      description: 'music_description',
      mediaImage: imagePixel,
      extras: { extras: 'any' }
    };
    let queueItem_1: avSession.AVQueueItem = {
      itemId: 1,
      description: queueItemDescription_1
    };
    let queueItemDescription_2: avSession.AVMediaDescription = {
      assetId: '002',
      title: 'music_name',
      subtitle: 'music_sub_name',
      description: 'music_description',
      mediaImage: imagePixel,
      extras: { extras: 'any' }
    };
    let queueItem_2: avSession.AVQueueItem = {
      itemId: 2,
      description: queueItemDescription_2
    };
    let queueItemsArray: avSession.AVQueueItem[] = [queueItem_1, queueItem_2];
    currentAVSession.setAVQueueItems(queueItemsArray, () => {
      console.info('Succeeded in setting AVQueueItems.');
    });
  }
}

setAVQueueTitle¹⁰⁺

setAVQueueTitle(title: string): Promise<void>

Sets a name for the playlist. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
title	string	Yes	Name of the playlist.

Return value

Type	Description
Promise<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example



let queueTitle = 'QUEUE_TITLE';
currentAVSession.setAVQueueTitle(queueTitle).then(() => {
  console.info('Succeeded in setting AVQueueTitle.');
});

setAVQueueTitle¹⁰⁺

setAVQueueTitle(title: string, callback: AsyncCallback<void>): 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<void>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example



let queueTitle = 'QUEUE_TITLE';
currentAVSession.setAVQueueTitle(queueTitle, () => {
  console.info('Succeeded in setting AVQueueTitle.');
});

setExtras¹⁰⁺

setExtras(extras: {[key: string]: Object}): Promise<void>

Sets a custom media data packet in the key-value pair format. This API is called by the provider. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

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).

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and AVSession Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified.2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example


import { avSession } from '@kit.AVSessionKit';
@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() { 
    Column() {
        Text(this.message)
          .onClick(() => {
            let currentAVSession: avSession.AVSession | undefined = undefined;
            let tag = "createNewSession";
            let context: Context = this.getUIContext().getHostContext() as Context;

            avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
              currentAVSession = data;
              if (currentAVSession !== undefined) {
(currentAVSession as avSession.AVSession).setExtras({extras : "This is custom media packet"}).then(() => {
                  console.info('Succeeded in setting extras.');
                })
              }
            });
          })
      }
    .width('100%')
    .height('100%')
  }
}

setExtras¹⁰⁺

setExtras(extras:{[key: string]: Object}, callback: AsyncCallback<void>): void

Sets a custom media data packet in the key-value pair format. It is called by the provider. This API uses an asynchronous callback to return the result.

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).
callback	AsyncCallback<void>	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 Universal Error Codes and AVSession Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Parameter verification failed.
6600101	Session service exception.
6600102	The session does not exist.

Example


import { avSession } from '@kit.AVSessionKit';
@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() { 
    Column() {
        Text(this.message)
          .onClick(()=>{
            let currentAVSession: avSession.AVSession | undefined = undefined;
            let tag = "createNewSession";
            let context: Context = this.getUIContext().getHostContext() as Context;

            avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
              currentAVSession = data;
              if (currentAVSession !== undefined) {
                (currentAVSession as avSession.AVSession).setExtras({extras : "This is custom media packet"}, () => {
                  console.info('Succeeded in setting extras.');
                })
              }
            });
          })
      }
    .width('100%')
    .height('100%')
  }
}

sendCustomData²⁰⁺

sendCustomData(data: Record<string, Object>): Promise<void>

Sends custom data to the remote device. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Multimedia.AVSession.AVCast

Parameters

Name	Type	Mandatory	Description
data	Record<string, Object>	Yes	Custom data filled by the application. Only objects with the key 'customData' and of the type string are parsed on the server.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.You are advised to:1.Scheduled retry.2.Destroy the current session or session controller and re-create it.
6600102	The session does not exist.

Example


import { avSession } from '@kit.AVSessionKit';
@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() { 
    Column() {
        Text(this.message)
          .onClick(()=>{
            let currentAVSession: avSession.AVSession | undefined = undefined;
            let tag = "createNewSession";
            let context: Context = this.getUIContext().getHostContext() as Context;

            avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
            currentAVSession = data;
            });
            if (currentAVSession !== undefined) {
            (currentAVSession as avSession.AVSession).sendCustomData({customData : "This is custom data"}).then(() => {
                console.info('Succeeded in sending custom data.');
            })
            }
          })
      }
    .width('100%')
    .height('100%')
  }
}

enableDesktopLyric²³⁺

enableDesktopLyric(enable: boolean): Promise<void>

Sets whether to enable the desktop lyrics feature for the current session. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Model restriction: This API can be used only in the stage model.

Parameters

Name	Type	Mandatory	Description
enable	boolean	Yes	Whether to enable the desktop lyrics feature. true to enable; false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.
6600111	The desktop lyrics feature is not supported.

Example


import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() {
    Column() {
      Text(this.message)
        .onClick(() => {
          let currentAVSession: avSession.AVSession | undefined = undefined;
          let tag = "createNewSession";
          let context: Context = this.getUIContext().getHostContext() as Context;

          avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
            currentAVSession = data;
          });
          if (currentAVSession !== undefined) {
            (currentAVSession as avSession.AVSession).enableDesktopLyric(true).then(() => {
              console.info('Succeeded in enabling desktop lyric.');
            })
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

setDesktopLyricVisible²³⁺

setDesktopLyricVisible(visible: boolean): Promise<void>

Sets whether to display desktop lyrics in the current session. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Model restriction: This API can be used only in the stage model.

Parameters

Name	Type	Mandatory	Description
visible	boolean	Yes	Whether to display desktop lyrics. true to display, false otherwise.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.
6600110	The desktop lyrics feature of this application is not enabled.
6600111	The desktop lyrics feature is not supported.

Example


import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() {
    Column() {
      Text(this.message)
        .onClick(() => {
          let currentAVSession: avSession.AVSession | undefined = undefined;
          let tag = "createNewSession";
          let context: Context = this.getUIContext().getHostContext() as Context;

          avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
            currentAVSession = data;
          });
          if (currentAVSession !== undefined) {
            (currentAVSession as avSession.AVSession).setDesktopLyricVisible(true).then(() => {
              console.info('Succeeded in setting desktop lyric visible.');
            })
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

isDesktopLyricVisible²³⁺

isDesktopLyricVisible(): Promise<boolean>

Checks whether desktop lyrics are displayed in the current session. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Model restriction: This API can be used only in the stage model.

Return value

Type	Description
Promise<boolean>	Promise used to return the result. If true is returned, the desktop lyrics are displayed. If false is returned, the desktop lyrics are not displayed.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.
6600110	The desktop lyrics feature of this application is not enabled.
6600111	The desktop lyrics feature is not supported.

Example


import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() {
    Column() {
      Text(this.message)
        .onClick(() => {
          let currentAVSession: avSession.AVSession | undefined = undefined;
          let tag = "createNewSession";
          let context: Context = this.getUIContext().getHostContext() as Context;
          avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
            currentAVSession = data;
          });
          if (currentAVSession !== undefined) {
            (currentAVSession as avSession.AVSession).isDesktopLyricVisible().then((visible: boolean) => {
              console.info(`isDesktopLyricVisible: ${visible}`);
            })
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

onDesktopLyricVisibilityChanged²³⁺

onDesktopLyricVisibilityChanged(callback: Callback<boolean>): void

Subscribes to the change events of the desktop lyrics visibility. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Model restriction: This API can be used only in the stage model.

Parameters

Name	Type	Mandatory	Description
callback	Callback<boolean>	Yes	Callback used to return the result. The value true indicates that the desktop lyrics are displayed, and false indicates the opposite.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example


import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() {
    Column() {
      Text(this.message)
        .onClick(() => {
          let currentAVSession: avSession.AVSession | undefined = undefined;
          let tag = "createNewSession";
          let context: Context = this.getUIContext().getHostContext() as Context;
          avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
            currentAVSession = data;
          });
          if (currentAVSession !== undefined) {
            (currentAVSession as avSession.AVSession).onDesktopLyricVisibilityChanged((visible: boolean) => {
              console.info(`desktop lyric visible state: ${visible}`);
            });
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

offDesktopLyricVisibilityChanged²³⁺

offDesktopLyricVisibilityChanged(callback?: Callback<boolean>): void

Unsubscribes from the change events of the desktop lyrics visibility. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Model restriction: This API can be used only in the stage model.

Parameters

Name	Type	Mandatory	Description
callback	Callback<boolean>	No	Callback function used to return the result. If the unsubscription is successful, err is undefined; otherwise, err is an error object. This parameter is optional. If it is not specified, the change events of all sessions' desktop lyrics visibility are unsubscribed.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example


import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() {
    Column() {
      Text(this.message)
        .onClick(() => {
          let currentAVSession: avSession.AVSession | undefined = undefined;
          let tag = "createNewSession";
          let context: Context = this.getUIContext().getHostContext() as Context;
          avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
            currentAVSession = data;
          });
          if (currentAVSession !== undefined) {
            (currentAVSession as avSession.AVSession).offDesktopLyricVisibilityChanged();
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

setDesktopLyricState²³⁺

setDesktopLyricState(state: DesktopLyricState): Promise<void>

Sets the desktop lyric state of the current session. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Model restriction: This API can be used only in the stage model.

Parameters

Name	Type	Mandatory	Description
state	DesktopLyricState	Yes	Desktop lyrics state.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.
6600110	The desktop lyrics feature of this application is not enabled.
6600111	The desktop lyrics feature is not supported.

Example


import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() {
    Column() {
      Text(this.message)
        .onClick(() => {
          let currentAVSession: avSession.AVSession | undefined = undefined;
          let tag = "createNewSession";
          let context: Context = this.getUIContext().getHostContext() as Context;

          avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
            currentAVSession = data;
          });
          if (currentAVSession !== undefined) {
            let state: avSession.DesktopLyricState = {
              isLocked: true,
            };
            (currentAVSession as avSession.AVSession).setDesktopLyricState(state).then(() => {
              console.info('Succeeded in setting desktop lyric state.');
            })
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

getDesktopLyricState²³⁺

getDesktopLyricState(): Promise<DesktopLyricState>

Obtains the desktop lyric state of the current session. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Model restriction: This API can be used only in the stage model.

Return value

Type	Description
Promise<DesktopLyricState>	Promise used to return the desktop lyrics state.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.
6600110	The desktop lyrics feature of this application is not enabled.
6600111	The desktop lyrics feature is not supported.

Example


import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() {
    Column() {
      Text(this.message)
        .onClick(() => {
          let currentAVSession: avSession.AVSession | undefined = undefined;
          let tag = "createNewSession";
          let context: Context = this.getUIContext().getHostContext() as Context;

          avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
            currentAVSession = data;
          });
          if (currentAVSession !== undefined) {
            (currentAVSession as avSession.AVSession).getDesktopLyricState()
              .then((state: avSession.DesktopLyricState) => {
                console.info(`getDesktopLyricState: ${state.isLocked}`);
              })
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

onDesktopLyricStateChanged²³⁺

onDesktopLyricStateChanged(callback: Callback<DesktopLyricState>): void

Subscribes to the change events of the desktop lyrics state. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Model restriction: This API can be used only in the stage model.

Parameters

Name	Type	Mandatory	Description
callback	Callback<DesktopLyricState>	Yes	Callback used to return the desktop lyrics state.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example


import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() {
    Column() {
      Text(this.message)
        .onClick(() => {
          let currentAVSession: avSession.AVSession | undefined = undefined;
          let tag = "createNewSession";
          let context: Context = this.getUIContext().getHostContext() as Context;

          avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
            currentAVSession = data;
          });
          if (currentAVSession !== undefined) {
            (currentAVSession as avSession.AVSession).onDesktopLyricStateChanged((state: avSession.DesktopLyricState) => {
              console.info(`desktop lyric isLocked : ${state.isLocked}`);
            })
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

offDesktopLyricStateChanged²³⁺

offDesktopLyricStateChanged(callback?: Callback<DesktopLyricState>): void

Unsubscribes from the change events of the desktop lyrics state. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.AVSession.Core

Model restriction: This API can be used only in the stage model.

Parameters

Name	Type	Mandatory	Description
callback	Callback<DesktopLyricState>	No	Callback used for unsubscription. If the unsubscription is successful, err is undefined; otherwise, err is an error object. This parameter is optional. If it is not specified, the change events of all sessions' desktop lyrics state are unsubscribed.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example


import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() {
    Column() {
      Text(this.message)
        .onClick(() => {
          let currentAVSession: avSession.AVSession | undefined = undefined;
          let tag = "createNewSession";
          let context: Context = this.getUIContext().getHostContext() as Context;
          avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
            currentAVSession = data;
          });
          if (currentAVSession !== undefined) {
            (currentAVSession as avSession.AVSession).offDesktopLyricStateChanged();
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

setBackgroundPlayMode²⁴⁺

setBackgroundPlayMode(mode: BackgroundPlayMode): Promise<void>

Sets the background playback mode. This API uses a promise to return the result.

It is recommended that this API be associated with the switch for enabling or disabling background playback in the application. If this association is not set, the default value is ENABLE_BACKGROUND_PLAY for audio sessions and DISABLE_BACKGROUND_PLAY for video sessions.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
mode	BackgroundPlayMode	Yes	Background playback mode.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

import { BusinessError } from '@kit.BasicServicesKit';
import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() {
    Column() {
      Text(this.message)
        .onClick(() => {
          let currentAVSession: avSession.AVSession | undefined = undefined;
          let tag = "createNewSession";
          let context: Context = this.getUIContext().getHostContext() as Context;
          avSession.createAVSession(context, tag, "audio", (err: BusinessError, data: avSession.AVSession) => {
            if (err) {
              console.error(`CreateAVSession BusinessError: code: ${err.code}, message: ${err.message}`);
            } else {
              currentAVSession = data;
            }
          });
          if (currentAVSession !== undefined) {
            try {
              (currentAVSession as avSession.AVSession).setBackgroundPlayMode(avSession.BackgroundPlayMode.ENABLE_BACKGROUND_PLAY);
            } catch (err) {
              console.error(`setBackgroundPlayMode BusinessError: code: ${err.code}, message: ${err.message}`);
            }
          }
        })
    }
    .width('100%')
    .height('100%')
  }
}

getController¹⁰⁺

getController(): Promise<AVSessionController>

Obtains the controller corresponding to this session. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Return value

Type	Description
Promise<AVSessionController>	Promise used to return the session controller.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example


import { avSession } from '@kit.AVSessionKit';

@Entry
@Component
struct Index {
  @State message: string = 'hello world';
  build() {
    Column() {
      Text(this.message)
        .onClick(async ()=>{
          let context: Context = this.getUIContext().getHostContext() as Context;
          let currentAVSession: avSession.AVSession = await avSession.createAVSession(context, 'SESSION_NAME', 'audio');
          let avSessionController: avSession.AVSessionController;
          currentAVSession.getController().then((avController: avSession.AVSessionController) => {
            avSessionController = avController;
            console.info(`Succeeded in getting controller, sessionid: ${avSessionController.sessionId}`);
          });
        })
    }
    .width('100%')
    .height('100%')
  }
}

getController¹⁰⁺

getController(callback: AsyncCallback<AVSessionController>): 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>	Yes	Callback used to return the session controller.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

import { avSession } from '@kit.AVSessionKit';


@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() {
    Column() {
      Text(this.message)
        .onClick(async () => {
          let context: Context = this.getUIContext().getHostContext() as Context;
          let currentAVSession: avSession.AVSession = await avSession.createAVSession(context, 'SESSION_NAME', 'audio');
          let avsessionController: avSession.AVSessionController;
          currentAVSession.getController((avcontroller: avSession.AVSessionController) => {
            avsessionController = avcontroller;
            console.info(`Succeeded in getting controller, sessionid: ${avsessionController.sessionId}`);
          });
        })
    }
    .width('100%')
    .height('100%')
  }
}

getAVCastController¹⁰⁺

getAVCastController(): Promise<AVCastController>

Obtains the cast controller when a casting connection is set up. This API uses a promise to return the result. If the session is not in the cast state, the controller returns null.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.AVCast

Return value

Type	Description
Promise<AVCastController>	Promise used to return the cast controller.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600102	The session does not exist.
6600109	The remote connection is not established.

Example



let avCastController: avSession.AVCastController;
currentAVSession.getAVCastController().then((avcontroller: avSession.AVCastController) => {
  avCastController = avcontroller;
  console.info('Succeeded in getting AV cast controller.');
});

getAVCastController¹⁰⁺

getAVCastController(callback: AsyncCallback<AVCastController>): void

Obtains the cast controller when a casting connection is set up. This API uses an asynchronous callback to return the result. If the session is not in the cast state, the controller returns null.

System capability: SystemCapability.Multimedia.AVSession.AVCast

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<AVCastController>	Yes	Callback used to return the cast controller.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600102	The session does not exist.
6600109	The remote connection is not established.

Example

let avCastController: avSession.AVCastController;
currentAVSession.getAVCastController((avcontroller: avSession.AVCastController) => {
  avCastController = avcontroller;
  console.info('Succeeded in getting AV cast controller.');
});

getOutputDevice¹⁰⁺

getOutputDevice(): Promise<OutputDeviceInfo>

Obtains information about the output device for this session. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Return value

Type	Description
Promise<OutputDeviceInfo>	Promise used to return the output device information.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example



currentAVSession.getOutputDevice().then((outputDeviceInfo: avSession.OutputDeviceInfo) => {
  console.info(`Succeeded in getting output device, devices length: ${outputDeviceInfo.devices.length}`);
})

getOutputDevice¹⁰⁺

getOutputDevice(callback: AsyncCallback<OutputDeviceInfo>): 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>	Yes	Callback used to return the information obtained.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.getOutputDevice((outputDeviceInfo: avSession.OutputDeviceInfo) => {
  console.info(`Succeeded in getting output device, devices length: ${outputDeviceInfo.devices.length}`);
});

activate¹⁰⁺

activate(): Promise<void>

Activates this session. A session can be used only after being activated. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Return value

Type	Description
Promise<void>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example



currentAVSession.activate().then(() => {
  console.info('Succeeded in activating.');
});

activate¹⁰⁺

activate(callback: AsyncCallback<void>): 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<void>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example



currentAVSession.activate(() => {
  console.info('Succeeded in activating.');
});

deactivate¹⁰⁺

deactivate(): Promise<void>

Deactivates this session. You can use activate to activate the session again. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Return value

Type	Description
Promise<void>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example



currentAVSession.deactivate().then(() => {
  console.info('Succeeded in deactivating.');
});

deactivate¹⁰⁺

deactivate(callback: AsyncCallback<void>): void

Deactivates this session. This API uses an asynchronous callback to return the result.

Deactivates this session. You can use activate to activate the session again.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example



currentAVSession.deactivate(() => {
  console.info('Succeeded in deactivating.');
});

destroy¹⁰⁺

destroy(): Promise<void>

Destroys this session. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Return value

Type	Description
Promise<void>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example



currentAVSession.destroy().then(() => {
  console.info('Succeeded in destroying.');
});

destroy¹⁰⁺

destroy(callback: AsyncCallback<void>): 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<void>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example



currentAVSession.destroy(() => {
  console.info('Succeeded in destroying.');
});

on('play')¹⁰⁺

on(type: 'play', callback: () => void): void

Subscribes to play command events. The subscription means that the application supports the play command.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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	() => void	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('play', () => {
  console.info('on play entry');
});

onPlay²²⁺

onPlay(callback: Callback<CommandInfo>): void

Subscribes to play command events. This API uses an asynchronous callback to return the result.

The application receives CommandInfo sent by the controller through the callback.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
callback	Callback<CommandInfo>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.onPlay((info: avSession.CommandInfo) => {
  console.info('on play entry');
});

on('pause')¹⁰⁺

on(type: 'pause', callback: () => void): void

Subscribes to pause command events. The subscription means that the application supports the pause command.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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	() => 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('pause', () => {
  console.info('on pause entry');
});

on('stop')¹⁰⁺

on(type:'stop', callback: () => void): void

Subscribes to stop command events. The subscription means that the application supports the stop command.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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	() => 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('stop', () => {
  console.info('on stop entry');
});

on('playNext')¹⁰⁺

on(type:'playNext', callback: () => void): void

Subscribes to playNext command events. The subscription means that the application supports the playNext command.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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	() => 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('playNext', () => {
  console.info('on playNext entry');
});

onPlayNext²²⁺

onPlayNext(callback: Callback<CommandInfo>): void

Subscribes to playNext command events. This API uses an asynchronous callback to return the result.

The application receives CommandInfo sent by the controller through the callback.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
callback	Callback<CommandInfo>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.onPlayNext((info: avSession.CommandInfo) => {
  console.info('on playNext entry');
});

on('playPrevious')¹⁰⁺

on(type:'playPrevious', callback: () => void): void

Subscribes to playPrevious command events. The subscription means that the application supports the playPrevious command.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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	() => 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('playPrevious', () => {
  console.info('on playPrevious entry');
});

onPlayPrevious²²⁺

onPlayPrevious(callback: Callback<CommandInfo>): void

Subscribes to playPrevious command events. This API uses an asynchronous callback to return the result.

The application receives CommandInfo sent by the controller through the callback.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
callback	Callback<CommandInfo>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.onPlayPrevious((info: avSession.CommandInfo) => {
  console.info('on playPrevious entry');
});

on('fastForward')¹⁰⁺

on(type: 'fastForward', callback: (time?: number) => void): void

Subscribes to fastForward command events. The subscription means that the application supports the fastForward command.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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	(time?: number) => void	Yes	Callback used for subscription. The time parameter in the callback indicates the time to seek to, in seconds.

Error codes

For details about the error codes, see Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('fastForward', (time?: number) => {
  console.info('on fastForward entry');
});

onFastForward²²⁺

onFastForward(callback: TwoParamCallback<number, CommandInfo>): void

Subscribes to fastForward command events. This API uses an asynchronous callback to return the result.

The application receives the fast-forward time parameter and CommandInfo sent by the controller through the callback.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
callback	TwoParamCallback<number, CommandInfo>	Yes	Callback used to return the result. It is used to process the fastForward operation.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.onFastForward((time: number, info: avSession.CommandInfo) => {
  console.info('on fastForward entry');
});

on('rewind')¹⁰⁺

on(type:'rewind', callback: (time?: number) => void): void

Subscribes to rewind command events.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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	(time?: number) => void	Yes	Callback used for subscription. The time parameter in the callback indicates the time to seek to, in seconds.

Error codes

For details about the error codes, see Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('rewind', (time?: number) => {
  console.info('on rewind entry');
});

onRewind²²⁺

onRewind(callback: TwoParamCallback<number, CommandInfo>): void

Subscribes to rewind command events. This API uses an asynchronous callback to return the result.

The application receives the rewind time parameter and CommandInfo sent by the controller through the callback.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
callback	TwoParamCallback<number, CommandInfo>	Yes	Callback used to return the result. It is used to process the rewind operation.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.onRewind((time: number, info: avSession.CommandInfo) => {
  console.info('on rewind entry');
});

on('playWithAssetId')²⁰⁺

on(type:'playWithAssetId', callback: Callback<string>): void

Subscribes to playback events with a given media asset ID.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The event 'playWithAssetId' is triggered when the media asset ID is played.
callback	Callback<string>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

let playWithAssetIdCallback = (assetId: string) => {
  console.info(`on playWithAssetId entry,  assetId = ${assetId}`);
}
currentAVSession.on('playWithAssetId', playWithAssetIdCallback);

off('playWithAssetId')²⁰⁺

off(type: 'playWithAssetId', callback?: Callback<string>): void

Unsubscribes from playback events with a given media asset ID. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'playWithAssetId' in this case.
callback	Callback<string>	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. The assetId parameter in the callback indicates the media asset ID.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('playWithAssetId');

on('seek')¹⁰⁺

on(type: 'seek', callback: (time: number) => void): void

Subscribes to seek command events.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('seek', (time: number) => {
  console.info(`on seek entry time : ${time}`);
});

on('setSpeed')¹⁰⁺

on(type: 'setSpeed', callback: (speed: number) => void): void

Subscribes to setSpeed command events.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('setSpeed', (speed: number) => {
  console.info(`on setSpeed speed : ${speed}`);
});

on('setLoopMode')¹⁰⁺

on(type: 'setLoopMode', callback: (mode: LoopMode) => void): void

Subscribes to setLoopMode command events.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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) => 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('setLoopMode', (mode: avSession.LoopMode) => {
  console.info(`on setLoopMode mode : ${mode}`);
});

on('setTargetLoopMode')¹⁸⁺

on(type: 'setTargetLoopMode', callback: Callback<LoopMode>): void

Subscribes to setTargetLoopMode command events.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The event 'setTargetLoopMode' is triggered when the command for setting the target loop mode is sent to the session.
callback	Callback<LoopMode>	Yes	Callback used for subscription. The LoopMode parameter in the callback indicates the target loop mode.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('setTargetLoopMode', (mode: avSession.LoopMode) => {
  console.info(`on setTargetLoopMode mode : ${mode}`);
});

on('toggleFavorite')¹⁰⁺

on(type: 'toggleFavorite', callback: (assetId: string) => void): void

Subscribes to toggleFavorite command events.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('toggleFavorite', (assetId: string) => {
  console.info(`on toggleFavorite mode : ${assetId}`);
});

on('skipToQueueItem')¹⁰⁺

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.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('skipToQueueItem', (itemId: number) => {
  console.info(`on skipToQueueItem id : ${itemId}`);
});

on('handleKeyEvent')¹⁰⁺

on(type: 'handleKeyEvent', callback: (event: KeyEvent) => void): void

Subscribes to key events of external devices such as Bluetooth and wired devices to listen for the play, pause, previous, next, fast-forward, and rewind commands in the key events.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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) => 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

import { KeyEvent } from '@kit.InputKit';

currentAVSession.on('handleKeyEvent', (event: KeyEvent) => {
  console.info(`on handleKeyEvent event : ${event}`);
});

on('outputDeviceChange')¹⁰⁺

on(type: 'outputDeviceChange', callback: (state: ConnectionState, device: OutputDeviceInfo) => void): void

Subscribes to output device change events. After the application integrates the multimedia.avCastPicker (AVCastPicker) component, the application receives the device change callback when the user switches the device through the component.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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, device: OutputDeviceInfo) => void	Yes	Callback function, where the device parameter specifies 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('outputDeviceChange', (state: avSession.ConnectionState, device: avSession.OutputDeviceInfo) => {
  console.info(`on outputDeviceChange device : ${device}`);
});

on('commonCommand')¹⁰⁺

on(type: 'commonCommand', callback: (command :string, args:{[key: string]: Object}) => void): void

Subscribes to custom control command change events.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

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	(command :string, args:{[key: string]: Object}) => void	Yes	Callback used for subscription. 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 parameters must be the same as those set in sendCommonCommand.

Error codes

For details about the error codes, see Universal Error Codes and AVSession Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example


import { avSession } from '@kit.AVSessionKit';
@Entry
@Component
struct Index {
  @State message: string = 'hello world';

  build() { 
    Column() {
        Text(this.message)
          .onClick(()=>{
            let currentAVSession: avSession.AVSession | undefined = undefined;
            let tag = "createNewSession";
            let context: Context = this.getUIContext().getHostContext() as Context;

            avSession.createAVSession(context, tag, "audio", (data: avSession.AVSession) => {
              currentAVSession = data;
              if (currentAVSession !== undefined) {
                (currentAVSession as avSession.AVSession).on('commonCommand', (commonCommand, args) => {
                    console.info(`OnCommonCommand, the command is ${commonCommand}, args: ${JSON.stringify(args)}`);
                });
              }
            });
          })
      }
    .width('100%')
    .height('100%')
  }
}

off('play')¹⁰⁺

off(type: 'play', callback?: () => void): void

Unsubscribes from play command events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'play' 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('play');

offPlay²²⁺

offPlay(callback?: Callback<CommandInfo>): void

Unsubscribes from play command events. This API uses an asynchronous callback to return the result.

If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
callback	Callback<CommandInfo>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.offPlay();

off('pause')¹⁰⁺

off(type: 'pause', callback?: () => void): void

Unsubscribes from pause command events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'pause' 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('pause');

off('stop')¹⁰⁺

off(type: 'stop', callback?: () => void): void

Unsubscribes from stop command events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'stop' 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('stop');

off('playNext')¹⁰⁺

off(type: 'playNext', callback?: () => void): void

Unsubscribes from playNext command events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'playNext' 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('playNext');

offPlayNext²²⁺

offPlayNext(callback?: Callback<CommandInfo>): void

Unsubscribes from playNext command events. This API uses an asynchronous callback to return the result.

If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
callback	Callback<CommandInfo>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.offPlayNext();

off('playPrevious')¹⁰⁺

off(type: 'playPrevious', callback?: () => void): void

Unsubscribes from playPrevious command events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'playPrevious' 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('playPrevious');

offPlayPrevious²²⁺

offPlayPrevious(callback?: Callback<CommandInfo>): void

Unsubscribes from playPrevious command events. This API uses an asynchronous callback to return the result.

If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
callback	Callback<CommandInfo>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.offPlayPrevious();

off('fastForward')¹⁰⁺

off(type: 'fastForward', callback?: () => void): void

Unsubscribes from fastForward command events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'fastForward' 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('fastForward');

offFastForward²²⁺

offFastForward(callback?: TwoParamCallback<number, CommandInfo>): void

Unsubscribes from fastForward command events. This API uses an asynchronous callback to return the result.

If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
callback	TwoParamCallback<number, CommandInfo>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.offFastForward();

off('rewind')¹⁰⁺

off(type: 'rewind', callback?: () => void): void

Unsubscribes from rewind command events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'rewind' 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('rewind');

offRewind²²⁺

offRewind(callback?: TwoParamCallback<number, CommandInfo>): void

Unsubscribes from rewind command events. This API uses an asynchronous callback to return the result.

If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
callback	TwoParamCallback<number, CommandInfo>	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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.offRewind();

off('seek')¹⁰⁺

off(type: 'seek', callback?: (time: number) => void): void

Unsubscribes from seek command events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('seek');

off('setSpeed')¹⁰⁺

off(type: 'setSpeed', callback?: (speed: number) => void): void

Unsubscribes from setSpeed command events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('setSpeed');

off('setLoopMode')¹⁰⁺

off(type: 'setLoopMode', callback?: (mode: LoopMode) => void): void

Unsubscribes from setLoopMode command events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

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) => 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('setLoopMode');

off('setTargetLoopMode')¹⁸⁺

off(type: 'setTargetLoopMode', callback?: Callback<LoopMode>): void

Unsubscribes from setTargetLoopMode command events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 18.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'setTargetLoopMode' in this case.
callback	Callback<LoopMode>	No	Callback used for unsubscription. The LoopMode parameter in the callback indicates the target 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.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('setTargetLoopMode');

off('toggleFavorite')¹⁰⁺

off(type: 'toggleFavorite', callback?: (assetId: string) => void): void

Unsubscribes from toggleFavorite command events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('toggleFavorite');

off('skipToQueueItem')¹⁰⁺

off(type: 'skipToQueueItem', callback?: (itemId: number) => void): void

Unsubscribes from the event that indicates an item in the playlist is selected. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('skipToQueueItem');

off('handleKeyEvent')¹⁰⁺

off(type: 'handleKeyEvent', callback?: (event: KeyEvent) => void): void

Unsubscribes from key events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

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) => 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('handleKeyEvent');

off('outputDeviceChange')¹⁰⁺

off(type: 'outputDeviceChange', callback?: (state: ConnectionState, device: OutputDeviceInfo) => void): void

Unsubscribes from playback device change events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

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, device: OutputDeviceInfo) => void	No	Callback function, where the device parameter specifies 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('outputDeviceChange');

off('commonCommand')¹⁰⁺

off(type: 'commonCommand', callback?: (command: string, args:{[key: string]: Object}) => void): void

Unsubscribes from custom control command change events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

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 Universal Error Codes and AVSession Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('commonCommand');

on('answer')¹¹⁺

on(type: 'answer', callback: Callback<void>): void

Subscribes to call answer events.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The event 'answer' is triggered when a call is answered.
callback	Callback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('answer', () => {
  console.info('on call answer');
});

off('answer')¹¹⁺

off(type: 'answer', callback?: Callback<void>): void

Unsubscribes from call answer events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'answer' 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('answer');

on('hangUp')¹¹⁺

on(type: 'hangUp', callback: Callback<void>): void

Subscribes to call hangup events.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The event 'hangUp' is triggered when a call is hung up.
callback	Callback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('hangUp', () => {
  console.info('on call hangUp');
});

off('hangUp')¹¹⁺

off(type: 'hangUp', callback?: Callback<void>): void

Unsubscribes from call answer events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'hangUp' 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('hangUp');

on('toggleCallMute')¹¹⁺

on(type: 'toggleCallMute', callback: Callback<void>): void

Subscribes to call mute events.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The event 'toggleCallMute' is triggered when a call is muted or unmuted.
callback	Callback<void>	Yes	Callback used to return the result.

Error codes

For details about the error codes, see Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('toggleCallMute', () => {
  console.info('on call toggleCallMute');
});

off('toggleCallMute')¹¹⁺

off(type: 'toggleCallMute', callback?: Callback<void>): void

Unsubscribes from call mute events. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'toggleCallMute' 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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('toggleCallMute');

on('castDisplayChange')¹²⁺

on(type: 'castDisplayChange', callback: Callback<CastDisplayInfo>): void

Subscribes to cast display change events in the case of extended screens.

Multiple callbacks can be registered for this event. To ensure only the latest callback executes, unregister previous listeners first. Otherwise, all registered callbacks will fire on state changes.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.ExtendedDisplayCast

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The event 'castDisplayChange' is triggered when the cast display in the case of extended screens changes.
callback	Callback<CastDisplayInfo>	Yes	Callback used to return the information about the cast display.

Error codes

For details about the error codes, see Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

let castDisplay: avSession.CastDisplayInfo;
currentAVSession.on('castDisplayChange', (display: avSession.CastDisplayInfo) => {
    if (display.state === avSession.CastDisplayState.STATE_ON) {
        castDisplay = display;
        console.info(`Succeeded in castDisplayChange display : ${display.id} ON`);
    } else if (display.state === avSession.CastDisplayState.STATE_OFF){
        console.info(`Succeeded in castDisplayChange display : ${display.id} OFF`);
    }
});

off('castDisplayChange')¹²⁺

off(type: 'castDisplayChange', callback?: Callback<CastDisplayInfo>): void

Unsubscribes from cast display change events in the case of extended screens. If a callback is specified, the corresponding listener is unregistered. If no callback is specified, all listeners for the specified event are unregistered.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.ExtendedDisplayCast

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'castDisplayChange' in this case.
callback	Callback<CastDisplayInfo>	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 Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('castDisplayChange');

stopCasting¹⁰⁺

stopCasting(callback: AsyncCallback<void>): 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<void>	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.

ID	Error Message
6600109	The remote connection is not established.

Example

currentAVSession.stopCasting(() => {
  console.info('Succeeded in stopping casting.');
});

stopCasting¹⁰⁺

stopCasting(): Promise<void>

Stops castings. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.AVCast

Return value

Type	Description
Promise<void>	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.

ID	Error Message
6600109	The remote connection is not established.

Example



currentAVSession.stopCasting().then(() => {
  console.info('Succeeded in stopping casting.');
});

getOutputDeviceSync¹⁰⁺

getOutputDeviceSync(): OutputDeviceInfo

Obtains the output device information. This API returns the result synchronously.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Return value

Type	Description
OutputDeviceInfo	Information about the output device.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example



let currentOutputDevice: avSession.OutputDeviceInfo = currentAVSession.getOutputDeviceSync();

getAllCastDisplays¹²⁺

getAllCastDisplays(): Promise<Array<CastDisplayInfo>>

Obtains all displays that support extended screen projection in the current system. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.ExtendedDisplayCast

Return value

Type	Description
Promise<Array<CastDisplayInfo>>	Promise used to return the information about all the cast displays.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example



let castDisplay: avSession.CastDisplayInfo;
currentAVSession.getAllCastDisplays().then((data: Array< avSession.CastDisplayInfo >) => {
    if (data.length >= 1) {
       castDisplay = data[0];
     }
    });

on('playFromAssetId')^(deprecated)

on(type:'playFromAssetId', callback: (assetId: number) => void): void

Subscribes to playback events with a given media asset ID.

NOTE This API is supported since API version 11 and deprecated since API version 20. You are advised to use on('playWithAssetId') instead.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The event 'playFromAssetId' is triggered when the media asset ID is played.
callback	(assetId: number) => void	Yes	Callback used to return the result. The assetId parameter in the callback indicates the media asset ID.

Error codes

For details about the error codes, see Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('playFromAssetId', (assetId: number) => {
  console.info('on playFromAssetId entry');
});

off('playFromAssetId')^(deprecated)

off(type: 'playFromAssetId', callback?: (assetId: number) => void): void

NOTE This API is supported since API version 11 and deprecated since API version 20. You are advised to use off('playWithAssetId') instead.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.AVSession.Core

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'playFromAssetId' in this case.
callback	(assetId: number) => 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. The assetId parameter in the callback indicates the media asset ID.

Error codes

For details about the error codes, see Universal Error Codes and AVSession Management Error Codes.

ID	Error Message
401	parameter check failed. 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('playFromAssetId');

on('customDataChange')²⁰⁺

on(type: 'customDataChange', callback: Callback<Record<string, Object>>): void

Subscribes to events indicating that custom data is sent to a remote device.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Multimedia.AVSession.AVCast

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The event 'customDataChange' is triggered when the provider sends custom data.
callback	Callback<Record<string, Object>>	Yes	Callback used to receive the custom data.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.on('customDataChange', (callback) => {
    console.info(`Caught customDataChange event,the new callback is: ${JSON.stringify(callback)}`);
});

off('customDataChange')²⁰⁺

off(type: 'customDataChange', callback?: Callback<Record<string, Object>>): void

Unsubscribes from events indicating that custom data is sent to a remote device.

Atomic service API: This API can be used in atomic services since API version 20.

System capability: SystemCapability.Multimedia.AVSession.AVCast

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type, which is 'customDataChange' in this case.
callback	Callback<Record<string, Object>>	No	Callback used for unsubscription. The callback parameter is optional. If it is not specified, all the subscriptions to the specified event are canceled for this session.

Error codes

For details about the error codes, see AVSession Management Error Codes.

ID	Error Message
6600101	Session service exception.
6600102	The session does not exist.

Example

currentAVSession.off('customDataChange');

Interface (AVSession)

Modules to Import

Properties

setAVMetadata10+

setAVMetadata10+

setCallMetadata11+

setCallMetadata11+

setAVCallState11+

setAVCallState11+

setAVPlaybackState10+

setAVPlaybackState10+

setLaunchAbility10+

setLaunchAbility10+

dispatchSessionEvent10+

dispatchSessionEvent10+

setAVQueueItems10+

setAVQueueItems10+

setAVQueueTitle10+

setAVQueueTitle10+

setExtras10+

setExtras10+

sendCustomData20+

enableDesktopLyric23+

setDesktopLyricVisible23+

isDesktopLyricVisible23+

onDesktopLyricVisibilityChanged23+

offDesktopLyricVisibilityChanged23+

setDesktopLyricState23+

getDesktopLyricState23+

onDesktopLyricStateChanged23+

offDesktopLyricStateChanged23+

setBackgroundPlayMode24+

getController10+

getController10+

getAVCastController10+

getAVCastController10+

getOutputDevice10+

getOutputDevice10+

activate10+

activate10+

deactivate10+

deactivate10+

destroy10+

destroy10+

on('play')10+

onPlay22+

on('pause')10+

on('stop')10+

on('playNext')10+

onPlayNext22+

on('playPrevious')10+

onPlayPrevious22+

on('fastForward')10+

onFastForward22+

on('rewind')10+

onRewind22+

on('playWithAssetId')20+

off('playWithAssetId')20+

on('seek')10+

on('setSpeed')10+

on('setLoopMode')10+

on('setTargetLoopMode')18+

on('toggleFavorite')10+

on('skipToQueueItem')10+

on('handleKeyEvent')10+

on('outputDeviceChange')10+

on('commonCommand')10+

off('play')10+

offPlay22+

off('pause')10+

off('stop')10+

off('playNext')10+

offPlayNext22+

off('playPrevious')10+

offPlayPrevious22+

off('fastForward')10+

offFastForward22+

off('rewind')10+

offRewind22+

off('seek')10+

setAVMetadata¹⁰⁺

setAVMetadata¹⁰⁺

setCallMetadata¹¹⁺

setCallMetadata¹¹⁺

setAVCallState¹¹⁺

setAVCallState¹¹⁺

setAVPlaybackState¹⁰⁺

setAVPlaybackState¹⁰⁺

setLaunchAbility¹⁰⁺

setLaunchAbility¹⁰⁺

dispatchSessionEvent¹⁰⁺

dispatchSessionEvent¹⁰⁺

setAVQueueItems¹⁰⁺

setAVQueueItems¹⁰⁺

setAVQueueTitle¹⁰⁺

setAVQueueTitle¹⁰⁺

setExtras¹⁰⁺

setExtras¹⁰⁺

sendCustomData²⁰⁺

enableDesktopLyric²³⁺

setDesktopLyricVisible²³⁺

isDesktopLyricVisible²³⁺

onDesktopLyricVisibilityChanged²³⁺

offDesktopLyricVisibilityChanged²³⁺

setDesktopLyricState²³⁺

getDesktopLyricState²³⁺

onDesktopLyricStateChanged²³⁺

offDesktopLyricStateChanged²³⁺

setBackgroundPlayMode²⁴⁺

getController¹⁰⁺

getController¹⁰⁺

getAVCastController¹⁰⁺

getAVCastController¹⁰⁺

getOutputDevice¹⁰⁺

getOutputDevice¹⁰⁺

activate¹⁰⁺

activate¹⁰⁺

deactivate¹⁰⁺

deactivate¹⁰⁺

destroy¹⁰⁺

destroy¹⁰⁺

on('play')¹⁰⁺

onPlay²²⁺

on('pause')¹⁰⁺

on('stop')¹⁰⁺

on('playNext')¹⁰⁺

onPlayNext²²⁺

on('playPrevious')¹⁰⁺

onPlayPrevious²²⁺

on('fastForward')¹⁰⁺

onFastForward²²⁺

on('rewind')¹⁰⁺

onRewind²²⁺

on('playWithAssetId')²⁰⁺

off('playWithAssetId')²⁰⁺

on('seek')¹⁰⁺

on('setSpeed')¹⁰⁺

on('setLoopMode')¹⁰⁺

on('setTargetLoopMode')¹⁸⁺

on('toggleFavorite')¹⁰⁺

on('skipToQueueItem')¹⁰⁺

on('handleKeyEvent')¹⁰⁺

on('outputDeviceChange')¹⁰⁺

on('commonCommand')¹⁰⁺

off('play')¹⁰⁺

offPlay²²⁺

off('pause')¹⁰⁺

off('stop')¹⁰⁺

off('playNext')¹⁰⁺

offPlayNext²²⁺

off('playPrevious')¹⁰⁺

offPlayPrevious²²⁺

off('fastForward')¹⁰⁺

offFastForward²²⁺

off('rewind')¹⁰⁺

offRewind²²⁺

off('seek')¹⁰⁺

off('setSpeed')¹⁰⁺

off('setLoopMode')¹⁰⁺

off('setTargetLoopMode')¹⁸⁺