Classes
class	MusicCacheStatusType
	Cache status of music resources.

class	MusicContentCenterStateReason
	Request status codes of the music content center.

class	PreloadState
	The loading state of music resources.

Public Member Functions
abstract int	initialize (MusicContentCenterConfiguration configuration)
	Initializes `IAgoraMusicContentCenter`. More...

abstract int	renewToken (String token)
	Renews the Token. More...

abstract IAgoraMusicPlayer	createMusicPlayer ()
	Creates a music player. More...

abstract int	destroyMusicPlayer (IAgoraMusicPlayer player)
	Destroys the music player object. More...

abstract int	registerEventHandler (IMusicContentCenterEventHandler eventHandler)
	Registers the callback events for the music content center. More...

abstract int	unregisterEventHandler ()
	Unregisters the event callback for the music content center. More...

abstract String	preload (long songCode)
	Preloads copyright music resources. More...

abstract int	preload (long songCode, String jsonOption)
	Preloads music resources. More...

abstract int	isPreloaded (long songCode)
	Checks whether a music resource has been preloaded. More...

abstract String	getMusicCharts ()
	Retrieves all music charts. More...

String	getMusicCollectionByMusicChartId (int musicChartId, int page, int pageSize)
	Retrieves the list of music resources from a specified music chart by its ID. More...

abstract String	getMusicCollectionByMusicChartId (int musicChartId, int page, int pageSize, String jsonOption)
	Retrieves the list of music resources from a specified music chart by its ID. More...

String	searchMusic (String keyword, int page, int pageSize)
	Searches for music resources. More...

abstract String	searchMusic (String keyword, int page, int pageSize, String jsonOption)
	Searches for music resources. More...

abstract String	getLyric (long songCode, int lyricType)
	Retrieves the download URL for the lyrics of a music resource. More...

abstract int	removeCache (long songCode)
	Deletes a cached music resource. More...

abstract MusicCacheInfo[]	getCaches ()
	Retrieves information about cached music resources. More...

abstract String	getSongSimpleInfo (long songCode)
	Retrieves detailed information about a specific music resource. More...

abstract long	getInternalSongCode (long songCode, String jsonOption)
	Creates an internal identifier for the chorus clip of a music resource. More...

Static Public Member Functions
static synchronized IAgoraMusicContentCenter	create (RtcEngine rtcEngine)

static synchronized void	destroy ()
	Destroys the `IAgoraMusicContentCenter` instance. More...

Protected Member Functions
abstract void	doDestroy ()

Member Function Documentation

◆ destroy()

static synchronized void io.agora.musiccontentcenter.IAgoraMusicContentCenter.destroy ( )

static

Destroys the IAgoraMusicContentCenter instance.

You must call this method before calling the destroy() method of RtcEngine.

◆ initialize()

abstract int io.agora.musiccontentcenter.IAgoraMusicContentCenter.initialize ( MusicContentCenterConfiguration configuration )

abstract

Initializes IAgoraMusicContentCenter.

You must call this method to initialize IAgoraMusicContentCenter before calling any other methods in the IAgoraMusicContentCenter class.

Parameters

configuration The settings for IAgoraMusicContentCenter. See MusicContentCenterConfiguration for details.

Returns

0: The method call succeeds.
< 0: The method call fails. See Error Codes for details and troubleshooting suggestions.

◆ renewToken()

abstract int io.agora.musiccontentcenter.IAgoraMusicContentCenter.renewToken ( String token )

abstract

Renews the Token.

When the Token used for authentication is about to expire or has already expired, you can call this method to pass in a newly generated Token.

Parameters

token The new Token.

Returns

0: Method call succeeds.
< 0: Method call fails. See Error Codes for details and troubleshooting suggestions.

◆ createMusicPlayer()

abstract IAgoraMusicPlayer io.agora.musiccontentcenter.IAgoraMusicContentCenter.createMusicPlayer ( )

abstract

Creates a music player.

If you need to play music resources from the music content center, you must call this method first to create a music player.

Returns

If the method call succeeds: returns an IAgoraMusicPlayer object.
If the method call fails: returns a null pointer.

◆ destroyMusicPlayer()

abstract int io.agora.musiccontentcenter.IAgoraMusicContentCenter.destroyMusicPlayer ( IAgoraMusicPlayer player )

abstract

Destroys the music player object.

When you no longer need to use the music player, you can call this method to destroy the music player object. If you need to use the music player again after destruction, you must call createMusicPlayer to recreate a music player object. Call timing: You can call this method either before or after joining a channel, but make sure to call it before the destroy() method of RtcEngine.

Parameters

player The IAgoraMusicPlayer object.

Returns

0: The method call succeeds.
< 0: The method call fails. See Error Codes for details and troubleshooting tips.

◆ registerEventHandler()

abstract int io.agora.musiccontentcenter.IAgoraMusicContentCenter.registerEventHandler ( IMusicContentCenterEventHandler eventHandler )

abstract

Registers the callback events for the music content center.

Parameters

eventHandler The callback events to be registered. See IMusicContentCenterEventHandler for details.

Returns

0: The method call succeeds.
< 0: The method call fails. See Error Codes for details and troubleshooting suggestions.

◆ unregisterEventHandler()

abstract int io.agora.musiccontentcenter.IAgoraMusicContentCenter.unregisterEventHandler ( )

abstract

Unregisters the event callback for the music content center.

Returns

0: The method call succeeds.
< 0: The method call fails. See Error Codes for details and suggested solutions.

◆ preload() [1/2]

abstract String io.agora.musiccontentcenter.IAgoraMusicContentCenter.preload ( long songCode )

abstract

Preloads copyright music resources.

You can call this method to preload the copyright music resources you want to play. After the method is successfully called, the SDK triggers the onPreLoadEvent callback to report the event of preloading the copyright music resource. Before calling this method to preload copyright music resources, you need to call getMusicCollectionByMusicChartId(int musicChartId, int page, int pageSize) or searchMusic(String keyword, int page, int pageSize) to obtain the copyright music resources you want to play, and retrieve the music resource identifier (songCode) through the onMusicCollectionResult callback triggered by these methods.

Note: To destroy the RtcEngine object, make sure to call the destroy() method only after receiving the onPreLoadEvent callback.

Parameters

songCode The identifier of the copyright music resource.

Returns: A requestId, which is the unique identifier for this request.

◆ preload() [2/2]

abstract int io.agora.musiccontentcenter.IAgoraMusicContentCenter.preload	(	long	songCode,
		String	jsonOption
	)

abstract

Preloads music resources.

Deprecated:: use preload(long songCode) instead.

You can call this method to preload the music resources you want to play. After this method is successfully called, the SDK triggers the onPreLoadEvent callback to report the preload event. Before calling this method to preload music resources, you need to call getMusicCollectionByMusicChartId(int musicChartId, int page, int pageSize) or searchMusic(String keyword, int page, int pageSize) to retrieve the music resources you want to play, and obtain the resource identifier (songCode) from the onMusicCollectionResult callback triggered by those methods.

Note: To destroy the RtcEngine object, make sure to call the destroy() method after receiving the onPreLoadEvent callback.

Parameters

songCode The identifier of the music resource.

jsonOption

Extended JSON field. Agora charges based on the application scenario you set in the sceneType field. Different scenarios are billed at different rates. Refer to the billing documentation for details.

1: Live streaming scenario: Karaoke and background music playback.
2: Live streaming scenario: Background music playback.
3: (Default) Voice chat scenario: Karaoke.
4: Voice chat scenario: Background music playback.
5: VR scenario: Karaoke and background music playback. If you need to switch to a different scenario, you must call this method again and pass the new sceneType value in this field. Example: {"sceneType":1}

Returns

0: The method call succeeds.
< 0: The method call fails. See Error Codes for details and troubleshooting.

◆ isPreloaded()

abstract int io.agora.musiccontentcenter.IAgoraMusicContentCenter.isPreloaded ( long songCode )

abstract

Checks whether a music resource has been preloaded.

This method is a synchronous call. To preload a new music resource, you can call preload(long songCode).

Parameters

songCode The identifier of the music resource, used to specify a music resource.

Returns

0: The method call is successful, and the music resource has been preloaded.
< 0: The method call fails. Refer to Error Codes for details and suggested solutions.

◆ getMusicCharts()

abstract String io.agora.musiccontentcenter.IAgoraMusicContentCenter.getMusicCharts ( )

abstract

Retrieves all music charts.

When you call this method, the SDK triggers the onMusicChartsResult callback to report detailed information about the music charts.

Returns: A requestId, which is the unique identifier for this request.

◆ getMusicCollectionByMusicChartId() [1/2]

String io.agora.musiccontentcenter.IAgoraMusicContentCenter.getMusicCollectionByMusicChartId	(	int	musicChartId,
		int	page,
		int	pageSize
	)

Retrieves the list of music resources from a specified music chart by its ID.

After a successful call to this method, the SDK triggers the onMusicCollectionResult callback to report detailed information about the music resources in the chart.

Parameters

musicChartId	The ID of the music chart, which you can obtain through the `onMusicChartsResult` callback. You can also use the RESTful API to `get the full song list from the music library` or `get the incremental song list`.
page	The current page number, starting from 1 by default.
pageSize	The total number of pages in the current list of music resources. The maximum value is 50.

Returns: A requestId, which uniquely identifies this request.

◆ getMusicCollectionByMusicChartId() [2/2]

abstract String io.agora.musiccontentcenter.IAgoraMusicContentCenter.getMusicCollectionByMusicChartId	(	int	musicChartId,
		int	page,
		int	pageSize,
		String	jsonOption
	)

abstract

Retrieves the list of music resources from a specified music chart by its ID.

After a successful call to this method, the SDK triggers the onMusicCollectionResult callback to report detailed information about the music resources in the chart.

Parameters

musicChartId The ID of the music chart, which you can obtain via the onMusicChartsResult callback. You can also use the RESTful API to get the full music library list or get the incremental music list.

page The current page number, starting from 1 by default.

pageSize The total number of pages for the music resource list. The maximum value is 50.

jsonOption

An optional JSON extension field, default is NULL. You can use this field to filter the music resources you need. Currently, it supports filtering for scorable music resources and chorus segments of music resources:

Key	Value	Example
pitchType	Whether the music resource supports scoring: - 1: Scorable music resources. - 2: Non-scorable music resources.	{"pitchType":1}
needHighPart	Whether the chorus segment resource is needed: - `true`: Chorus segment required. - `false`: Chorus segment not required.	{"needHighPart":true}

Returns: A requestId, which is the unique identifier for this request.

◆ searchMusic() [1/2]

String io.agora.musiccontentcenter.IAgoraMusicContentCenter.searchMusic	(	String	keyword,
		int	page,
		int	pageSize
	)

Searches for music resources.

After this method is successfully called, the SDK triggers the onMusicCollectionResult callback to report the retrieved list of music resources.

Parameters

keyword	The search keyword. Supports searching by song title or artist name.
page	The target page number of the music resource list you want to retrieve.
pageSize	The maximum number of music resources displayed per page. The maximum value is 50.

Returns: A requestId that uniquely identifies this request.

◆ searchMusic() [2/2]

abstract String io.agora.musiccontentcenter.IAgoraMusicContentCenter.searchMusic	(	String	keyword,
		int	page,
		int	pageSize,
		String	jsonOption
	)

abstract

Searches for music resources.

After this method is successfully called, the SDK triggers the onMusicCollectionResult callback to report the retrieved list of music resources.

Parameters

keyword The search keyword. Supports searching by song title or artist name.

page The target page number of the music resource list you want to retrieve.

pageSize The maximum number of music resources displayed per page. The maximum value is 50.

jsonOption

An optional JSON extension field. Defaults to NULL. You can use this field to filter the music resources you need. Currently supports filtering by whether the music resource supports scoring and whether it includes a chorus segment:

Key	Value	Example
pitchType	Whether scoring is supported: - 1: Music resources that support scoring. - 2: Those that do not.	{"pitchType":1}
needHighPart	Whether a chorus segment is needed: - `true`: Chorus segment is required. - `false`: Not required.	{"needHighPart":true}

Returns: A requestId that uniquely identifies this request.

◆ getLyric()

abstract String io.agora.musiccontentcenter.IAgoraMusicContentCenter.getLyric	(	long	songCode,
		int	lyricType
	)

abstract

Retrieves the download URL for the lyrics of a music resource.

After this method is successfully called, the SDK triggers the onLyricResult callback to report the download URL of the lyrics.

Parameters

songCode	The identifier of the music resource used to specify the music.
lyricType	The type of lyrics: 0: xml format. 1: lrc format.

Returns: A requestId that uniquely identifies this request.

◆ removeCache()

abstract int io.agora.musiccontentcenter.IAgoraMusicContentCenter.removeCache ( long songCode )

abstract

Deletes a cached music resource.

You can call this method to delete a cached music resource. To delete multiple music resources, you can call this method multiple times.

Note: This method does not delete cached music resources that are currently playing.

Parameters

songCode The identifier of the music resource to be deleted.

Returns

0: The method call succeeds and the music resource is deleted.
< 0: The method call fails. Refer to Error Codes for details and troubleshooting suggestions.

◆ getCaches()

abstract MusicCacheInfo [] io.agora.musiccontentcenter.IAgoraMusicContentCenter.getCaches ( )

abstract

Retrieves information about cached music resources.

Before calling this method, you need to pre-allocate a certain amount of memory to store information about the cached music resources. If you need to set the number of music resources that can be cached, you can configure it through the configuration parameter of initialize. When you no longer need the cached music resources, you should release the memory in a timely manner to avoid memory leaks.

Returns

If the method call succeeds, returns an array containing MusicCacheInfo objects.
If the method call fails, returns NULL.

◆ getSongSimpleInfo()

abstract String io.agora.musiccontentcenter.IAgoraMusicContentCenter.getSongSimpleInfo ( long songCode )

abstract

Retrieves detailed information about a specific music resource.

Before calling this method, you need to obtain the identifier of the corresponding music resource. You can do this by calling the getMusicCollectionByMusicChartId(int musicChartId, int page, int pageSize) or searchMusic(String keyword, int page, int pageSize) method to retrieve music resources, and obtain the music resource identifier (songCode) through the triggered onMusicCollectionResult callback. After you call this method, the SDK triggers the onSongSimpleInfoResult callback to report the detailed information of the music resource.

Parameters

songCode The identifier of the music resource, used to specify the music resource.

Returns: A requestId that uniquely identifies this request.

◆ getInternalSongCode()

abstract long io.agora.musiccontentcenter.IAgoraMusicContentCenter.getInternalSongCode	(	long	songCode,
		String	jsonOption
	)

abstract

Creates an internal identifier for the chorus clip of a music resource.

Applicable scenarios: Before you play the chorus clip of a music resource, you need to call this method to create an internal identifier for the chorus clip using the jsonOption parameter and the songCode of the music resource. This identifier serves as the unique reference for the resource. Once you get this identifier, you need to pass it as the songCode parameter when calling related methods to open, preload, or remove the resource.

Parameters

songCode The identifier of the music resource. You can obtain this by calling getMusicCollectionByMusicChartId(int musicChartId, int page, int pageSize) or searchMusic(String keyword, int page, int pageSize), and retrieve the songCode from the onMusicCollectionResult callback triggered by these methods.

jsonOption

Extended JSON field, defaults to NULL. Currently supports the following values:

Key	Value	Example
sceneType	Channel profile: - 1: Live streaming scenario: karaoke and background music playback. - 2: Live streaming scenario: background music playback. - 3: (Default) Voice chat scenario: karaoke. - 4: Voice chat scenario: background music playback. - 5: VR scenario: karaoke and background music playback. Note: Agora charges based on the `sceneType` you provide. Different channel profiles have different pricing rates. Refer to the billing documentation for details. To switch to a different channel profile, you must call this method again with a new `sceneType` value.	{"sceneType":1}
highPart	Index of the chorus clip. You can obtain the index from the `onMusicCollectionResult` callback. The index starts from 0.	{"format": {"highpart": 0}}

Returns

If the method call succeeds, returns the created internal identifier of the music resource.
< 0: The method call fails. Refer to Error Codes for details and troubleshooting advice.

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Member Function Documentation

◆ destroy()

◆ initialize()

◆ renewToken()

◆ createMusicPlayer()

◆ destroyMusicPlayer()

◆ registerEventHandler()

◆ unregisterEventHandler()

◆ preload() [1/2]

◆ preload() [2/2]

◆ isPreloaded()

◆ getMusicCharts()

◆ getMusicCollectionByMusicChartId() [1/2]

◆ getMusicCollectionByMusicChartId() [2/2]

◆ searchMusic() [1/2]

◆ searchMusic() [2/2]

◆ getLyric()

◆ removeCache()

◆ getCaches()

◆ getSongSimpleInfo()

◆ getInternalSongCode()