Agora Java API Reference for Android

Classes | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
io.agora.musiccontentcenter.IAgoraMusicContentCenter Class Referenceabstract

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