AgoraMusicContentCenter Class Reference

Inherits <NSObject>.

Instance Methods
(NSInteger)	- renewToken:
(NSInteger)	- registerEventDelegate:
(id< AgoraMusicPlayerProtocol > _Nullable)	- createMusicPlayerWithDelegate:
(NSInteger)	- destroyMusicPlayer:
(NSString *)	- getMusicCharts
(NSString *)	- getMusicCollectionWithMusicChartId:page:pageSize:jsonOption:
(NSString *)	- searchMusicWithKeyWord:page:pageSize:jsonOption:
(NSInteger)	- preloadWithSongCode:jsonOption:
(NSString *)	- preloadWithSongCode:
(NSInteger)	- isPreloadedWithSongCode:
(NSInteger)	- removeCacheWithSongCode:
(NSArray *)	- getCaches
(NSInteger)	- getInternalSongCode:jsonOption:
(NSString *)	- getLyricWithSongCode:lyricType:
(NSString *)	- getSongSimpleInfoWithSongCode:

Class Methods
(instancetype _Nullable)	+ sharedContentCenterWithConfig:
(void)	+ destroy

Method Documentation

sharedContentCenterWithConfig:

+ (instancetype _Nullable) sharedContentCenterWithConfig:

(AgoraMusicContentCenterConfig *)

config

Initializes AgoraMusicContentCenter.

You must call this method to initialize AgoraMusicContentCenter before calling any other methods under the AgoraMusicContentCenter class.

Parameters

config

The configuration for AgoraMusicContentCenter. See AgoraMusicContentCenterConfig for details.

Returns

• If the method call succeeds, returns an AgoraMusicContentCenter instance.
• If the method call fails, returns nil.

renewToken:

- (NSInteger) renewToken:

(NSString *_Nonnull)

token

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: The method call succeeds.
• < 0: The method call fails. See Error Codes for details and troubleshooting suggestions.

registerEventDelegate:

- (NSInteger) registerEventDelegate:

(id< AgoraMusicContentCenterEventDelegate > _Nullable)

eventDelegate

Registers the callback events for the music content center.

Parameters

eventDelegate

The callback event to be registered. See AgoraMusicContentCenterEventDelegate for details. Pass in nil if you want to remove a previously registered callback event.

Returns

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

createMusicPlayerWithDelegate:

- (id<AgoraMusicPlayerProtocol> _Nullable) createMusicPlayerWithDelegate:

(id< AgoraRtcMediaPlayerDelegate > _Nullable)

delegate

Creates a music player.

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

Parameters

delegate

See AgoraRtcMediaPlayerDelegate.

Returns

• If the method call succeeds: returns an AgoraMusicPlayerProtocol instance.
• If the method call fails: returns a null pointer.

destroyMusicPlayer:

- (NSInteger) destroyMusicPlayer:

(id< AgoraMusicPlayerProtocol >)

musicPlayer

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 createMusicPlayerWithDelegate: to create a new 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 AgoraRtcEngineKit.

Parameters

musicPlayer

The AgoraMusicPlayerProtocol object.

Returns

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

getMusicCharts

- (NSString *) getMusicCharts

Retrieves all music charts.

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

Returns

A requestId that uniquely identifies this request.

getMusicCollectionWithMusicChartId:page:pageSize:jsonOption:

- (NSString *) getMusicCollectionWithMusicChartId:		(NSInteger)	musicChartId
page:		(NSInteger)	page
pageSize:		(NSInteger)	pageSize
jsonOption:		(NSString *_Nullable)	jsonOption

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

After this method is successfully called, the SDK triggers the onMusicCollectionResult:result:reason: callback to report detailed information about the music resources in the chart.

Parameters

musicChartId	The ID of the music chart, which can be obtained through the onMusicChartsResult:result:reason: callback. You can also use the RESTful API to retrieve the complete music library or retrieve the incremental music list.
page	The current page number, starting from 1 by default.
pageSize	The total number of pages of the current music resource list. The maximum value is 50.
jsonOption	An optional JSON extension field, default is nil. You can use this field to filter the music resources you need. Currently supports filtering music resources that support scoring and music resources with chorus segments: Key Value Example pitchType Whether scoring is supported: - 1: music resources that support scoring. - 2: music resources that do not support scoring. {"pitchType":1} needHighPart Whether chorus segment resources are needed: - YES: chorus segment resources are needed. - NO: chorus segment resources are not needed. {"needHighPart":true}

Returns

A requestId that uniquely identifies this request.

searchMusicWithKeyWord:page:pageSize:jsonOption:

- (NSString *) searchMusicWithKeyWord:		(NSString *)	keyWord
page:		(NSInteger)	page
pageSize:		(NSInteger)	pageSize
jsonOption:		(NSString *_Nullable)	jsonOption

Search for music resources.

After this method is successfully called, the SDK triggers the onMusicCollectionResult:result:reason: 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 extended JSON field, default is nil. You can use this field to filter the music resources you need. Currently, it supports filtering music resources that are scorable and those with chorus segments: Key Value Example pitchType Whether the music resource supports scoring: - 1: scorable music resources. - 2: non-scorable music resources. {"pitchType":1} needHighPart Whether chorus segment resources are needed: - YES: chorus segment resources needed. - NO: chorus segment resources not needed. {"needHighPart":true}

Returns

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

preloadWithSongCode:jsonOption:

- (NSInteger) preloadWithSongCode:		(NSInteger)	songCode
jsonOption:		(NSString *_Nullable)	jsonOption

Preloads music resources.

Deprecated:

This method is deprecated. Use preload(songCode:) instead.

You can call this method to preload the music resources you want to play. After this method is called successfully, the SDK triggers the onPreLoadEvent:songCode:percent:lyricUrl:state:reason: callback to report the event of preloading music resources. Before calling this method to preload music resources, you need to call the getMusicCollectionWithMusicChartId:page:pageSize:jsonOption: or searchMusicWithKeyWord:page:pageSize:jsonOption: method to obtain the music resources you want to play. Then, retrieve the music resource ID (songCode) from the onMusicCollectionResult:result:reason: callback triggered by those methods.

Note

To destroy the AgoraRtcEngineKit object, make sure to wait for the onPreLoadEvent:songCode:percent:lyricUrl:state:reason: callback before calling the destroy method.

Parameters

songCode

The ID of the music resource, used to identify the music.

jsonOption

Extended JSON field. Agora charges based on the application scenario you pass in the sceneType field. Different application scenarios correspond to different rates. Refer to the Billing Instructions for details. 1: Channel profile: Karaoke and background music playback in live streaming. 2: Channel profile: Background music playback in live streaming. 3: (Default) Channel profile: Karaoke in voice chat. 4: Channel profile: Background music playback in voice chat. 5: Channel profile: Karaoke and background music playback in VR. 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. Refer to Error Codes for details and troubleshooting suggestions.

preloadWithSongCode:

- (NSString *) preloadWithSongCode:

(NSInteger)

songCode

Preloads a music resource.

You can call this method to preload a music resource that you want to play. After the method is called successfully, the SDK triggers the onPreLoadEvent:songCode:percent:lyricUrl:state:reason: callback to report the preload event of the music resource. Before calling this method to preload a music resource, you need to call either getMusicCollectionWithMusicChartId:page:pageSize:jsonOption: or searchMusicWithKeyWord:page:pageSize:jsonOption: to retrieve the music resource you want to play. Then, obtain the song code (songCode) from the onMusicCollectionResult:result:reason: callback triggered by these methods.

Note

To destroy the AgoraRtcEngineKit object, you must wait until you receive the onPreLoadEvent:songCode:percent:lyricUrl:state:reason: callback before calling the destroy method.

Parameters

songCode

The identifier of the music resource.

Returns

A requestId, which is the unique identifier of this request.

isPreloadedWithSongCode:

- (NSInteger) isPreloadedWithSongCode:

(NSInteger)

songCode

Checks whether a music resource has been preloaded.

This method is a synchronous call. To preload a new music resource, you can call preloadWithSongCode:.

Parameters

songCode

The identifier of the music resource used to specify a particular music resource.

Returns

• 0: The method call succeeds and the music resource has been preloaded.
• < 0: The method call fails. See Error Codes for more details and troubleshooting suggestions.

removeCacheWithSongCode:

- (NSInteger) removeCacheWithSongCode:

(NSInteger)

songCode

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. See Error Codes for details and troubleshooting suggestions.

getCaches

- (NSArray *) getCaches

Gets information about the cached music resources.

Before calling this method, you need to allocate sufficient memory to store information about the cached music resources.
If you want to set the number of music resources that can be cached, you can configure it through the config parameter in sharedContentCenterWithConfig:. When you no longer need the cached music resources, you should release the memory in time to prevent memory leaks.

Returns

• If the method call succeeds, returns an array containing AgoraMusicCacheInfo objects.
• If the method call fails, returns nil.

getInternalSongCode:jsonOption:

- (NSInteger) getInternalSongCode:		(NSInteger)	songCode
jsonOption:		(NSString *_Nullable)	jsonOption

Creates an ID for the chorus segment of a music resource.

Applicable scenarios: When you need to play the chorus segment of a music resource, you must call this method to create an ID for the chorus segment of the resource using the jsonOption parameter and the songCode of the music resource. This ID serves as the unique identifier of the resource. After obtaining this ID, you need to pass it as the songCode parameter when calling the corresponding methods to open, preload, or remove the resource.

Parameters

songCode

The unique identifier of the music resource. You can obtain it by calling the getMusicCollectionWithMusicChartId:page:pageSize:jsonOption: or searchMusicWithKeyWord:page:pageSize:jsonOption: method, and retrieve the songCode from the onMusicCollectionResult:result:reason: callback.

jsonOption

Extended JSON field, defaults to nil. The following values are currently supported: 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 you based on the channel profile you specify in sceneType. Different channel profiles correspond to different rates. Refer to the billing documentation for details. To switch channel profiles, you must call this method again and pass in a new sceneType value. {"sceneType":1} highPart The index of the chorus segment. You can obtain the index from the onMusicCollectionResult:result:reason: callback and pass it in. The index starts from 0. {"format": {"highpart": 0}}

Returns

• If the method call succeeds, returns the generated internal ID of the music resource.
• < 0: The method call fails. See Error Codes for details and troubleshooting suggestions.

getLyricWithSongCode:lyricType:

- (NSString *) getLyricWithSongCode:		(NSInteger)	songCode
lyricType:		(NSInteger)	lyricType

Gets the download URL for the lyrics of a music asset.

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

Parameters

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

Returns

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

getSongSimpleInfoWithSongCode:

- (NSString *) getSongSimpleInfoWithSongCode:

(NSInteger)

songCode

Retrieves detailed information of a specific music resource.

Before calling this method, you need to obtain the identifier of the corresponding music resource. You can retrieve music resources by calling the getMusicCollectionWithMusicChartId:page:pageSize:jsonOption: or searchMusicWithKeyWord:page:pageSize:jsonOption: methods, and obtain the music resource identifier (songCode) through the onMusicCollectionResult:result:reason: callback triggered by those methods. After you call this method, the SDK triggers the onSongSimpleInfoResult:songCode:simpleInfo:reason: 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, which uniquely identifies this request.

destroy

+ (void) destroy

Destroys the AgoraMusicContentCenter instance.

You must call this method before calling the destroy method of AgoraRtcEngineKit.

onMusicChartsResult:result:errorCode:

- (void) onMusicChartsResult:		(NSString *)	requestId
result:		(NSArray< AgoraMusicChartInfo * > *)	result
errorCode:		(AgoraMusicContentCenterStateReason)	errorCode

onMusicCollectionResult:result:errorCode:

- (void) onMusicCollectionResult:		(NSString *)	requestId
result:		(AgoraMusicCollection *)	result
errorCode:		(AgoraMusicContentCenterStateReason)	errorCode

onLyricResult:songCode:lyricUrl:errorCode:

- (void) onLyricResult:		(NSString *)	requestId
songCode:		(NSInteger)	songCode
lyricUrl:		(NSString *_Nullable)	lyricUrl
errorCode:		(AgoraMusicContentCenterStateReason)	errorCode

onSongSimpleInfoResult:songCode:simpleInfo:errorCode:

- (void) onSongSimpleInfoResult:		(NSString *)	requestId
songCode:		(NSInteger)	songCode
simpleInfo:		(NSString *_Nullable)	simpleInfo
errorCode:		(AgoraMusicContentCenterStateReason)	errorCode

onPreLoadEvent:songCode:percent:lyricUrl:state:errorCode:

- (void) onPreLoadEvent:		(NSString *)	requestId
songCode:		(NSInteger)	songCode
percent:		(NSInteger)	percent
lyricUrl:		(NSString *_Nullable)	lyricUrl
state:		(AgoraMusicContentCenterPreloadState)	state
errorCode:		(AgoraMusicContentCenterStateReason)	errorCode