Agora RTC Objective-C API Reference Refactor

Instance Methods | Class Methods
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