# 版权音乐 (/zh-CN/api-reference/rtc/android/play/drm)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## createMusicPlayer [#createmusicplayer]
创建一个音乐播放器。
```java
public abstract IAgoraMusicPlayer createMusicPlayer();
```
如果你需要播放来自音乐内容中心的音乐资源,必须先调用该方法。
### 返回值 [#返回值]
- 方法调用成功,返回 [IAgoraMusicPlayer](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer) 对象。
- 方法调用失败,返回 `null`。
### 所属接口类 [#所属接口类]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## destroy [#destroy]
销毁 [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter) 实例。
```java
public static synchronized void destroy()
```
你必须在调用 [destroy](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_destroy_imusiccontentcenter) 方法之前调用该方法。
### 所属接口类 [#所属接口类-1]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## destroy [#destroy-1]
销毁音乐播放器。
```java
@Deprecated @Override int destroy();
```
:::error[废弃]
该方法已废弃,请改用 [destroyMusicPlayer](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_destroymusicplayer)。
:::
### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [IAgoraMusicPlayer](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer)
## destroyMusicPlayer [#destroymusicplayer]
销毁音乐播放器对象。
```java
public abstract int destroyMusicPlayer(IAgoraMusicPlayer player);
```
如果在销毁后需要再次使用音乐播放器,必须调用 [createMusicPlayer](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_createmusicplayer) 方法重新创建。
### 调用时机 [#调用时机]
你可以在加入频道前或加入频道后调用此方法,但必须确保在调用 [destroy](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_destroy_imusiccontentcenter) 方法之前调用此方法。
### 参数 [#参数]
音乐播放器对象。详见 [IAgoraMusicPlayer](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer)。
### 返回值 [#返回值-2]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## getCaches [#getcaches]
获取已缓存的音乐资源信息。
```java
public abstract MusicCacheInfo[] getCaches();
```
在调用该方法前,你需要预先分配内存空间,用于存储已缓存音乐资源的信息。如果需要设置可缓存的音乐资源数量,可以通过 [initialize](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_initialize_imusiccontentcenter) 的 `configuration` 参数进行配置。当不再需要这些缓存的音乐资源时,应及时释放内存,避免内存泄漏。
### 返回值 [#返回值-3]
- 方法调用成功,返回包含 [MusicCacheInfo](/zh-CN/api-reference/rtc/android/class-musiccacheinfo) 对象的数组。
- 方法调用失败,返回 `null`。
### 所属接口类 [#所属接口类-4]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## getInternalSongCode [#getinternalsongcode]
创建音乐资源副歌片段的内部标识符。
```java
public abstract long getInternalSongCode(long songCode, String jsonOption);
```
在播放音乐资源的副歌片段前,需调用该方法,结合音乐资源的 `songCode` 和 `jsonOption` 参数创建副歌片段的内部标识符。该标识符作为资源的唯一引用。在调用相关方法以打开、预加载或移除资源时,应将该标识符作为 `songCode` 参数传入。
### 参数 [#参数-1]
音乐资源的标识符。可通过调用 `getMusicCollectionByMusicChartId` 或 `searchMusic` 获取,并从这两个方法触发的 [onMusicCollectionResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调中获取 `songCode`。
:::note
注: `sceneType` 会影响计费方式。不同频道场景的计费标准不同,详见计费文档。若需切换频道场景,必须使用新的 `sceneType` 值重新调用该方法。
:::
扩展 JSON 字段,默认为 `null`。目前支持以下字段:
- sceneType:场景类型。1:直播场景,在线 K 歌房和背景音乐播放;2:直播场景,背景音乐播放;3:(默认)声动语聊场景,在线 K 歌房;4:声动语聊场景,背景音乐播放;5:VR 场景,在线 K 歌房和背景音乐播放。示例:`{"sceneType":1}`。
- highPart:副歌片段的索引,从 [onMusicCollectionResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调中获取,索引从 0 开始。示例:`{"format": {"highpart": 0}}`。
### 返回值 [#返回值-4]
- 方法调用成功,返回创建的音乐资源内部标识符。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## getLyric [#getlyric]
获取音乐资源歌词的下载链接。
```java
public abstract String getLyric(long songCode, int lyricType);
```
### 相关回调 [#相关回调]
调用该方法后,SDK 会触发 [onLyricResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 回调。
### 参数 [#参数-2]
指定音乐资源的标识符。
歌词格式类型:
- 0:xml 格式。
- 1:lrc 格式。
### 返回值 [#返回值-5]
- 方法调用成功时,返回唯一标识该请求的 `requestId`。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-6]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## getMusicCharts [#getmusiccharts]
获取所有音乐排行榜。
```java
public abstract String getMusicCharts();
```
调用该方法时,SDK 会触发 [onMusicChartsResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) 回调,返回音乐排行榜的详细信息。
### 相关回调 [#相关回调-1]
该方法调用后会触发 [onMusicChartsResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) 回调。
### 返回值 [#返回值-6]
- 方法调用成功时,返回请求的唯一标识符 `requestId`。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-7]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## getMusicCollectionByMusicChartId [1/2] [#getmusiccollectionbymusicchartid-12]
根据音乐榜单 ID 获取音乐资源列表。
```java
public String getMusicCollectionByMusicChartId(int musicChartId, int page, int pageSize)
```
成功调用该方法后,SDK 会触发 [onMusicCollectionResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调,返回榜单中的音乐资源详细信息。
### 参数 [#参数-3]
音乐榜单的 ID,可通过 [onMusicChartsResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) 回调获取。
:::note
注: 你也可以使用 RESTful API 获取“音乐库完整歌曲列表”或“增量歌曲列表”。
:::
当前页码,默认从 1 开始。
当前音乐资源列表中的总页数,最大值为 50。
### 返回值 [#返回值-7]
- 方法调用成功时,返回唯一标识此次请求的 `requestId`。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-8]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## getMusicCollectionByMusicChartId [2/2] [#getmusiccollectionbymusicchartid-22]
根据音乐榜单 ID 获取音乐资源列表。
```java
public abstract String getMusicCollectionByMusicChartId(int musicChartId, int page, int pageSize, String jsonOption);
```
成功调用该方法后,SDK 会触发 [onMusicCollectionResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调,返回榜单中的音乐资源详细信息。
### 相关回调 [#相关回调-2]
成功调用该方法后,SDK 会触发 [onMusicCollectionResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调,返回榜单中的音乐资源详细信息。
### 参数 [#参数-4]
音乐榜单的 ID。可通过 [onMusicChartsResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) 回调获取。你也可以使用 RESTful API 获取完整音乐库列表或增量音乐列表。
当前页码,从 1 开始。
每页返回的音乐资源数量,最大值为 50。
可选的 JSON 扩展字段,默认为 `null`。你可以使用该字段筛选所需的音乐资源。目前支持以下筛选项:
- `pitchType`:音乐资源是否支持评分。
- `1`:可评分音乐资源。
- `2`:不可评分音乐资源。
- `needHighPart`:是否需要合唱片段资源。
- true:需要合唱片段。
- false:不需要合唱片段。
示例:`{"pitchType":1}`,`{"needHighPart":true}`。
### 返回值 [#返回值-8]
- 方法调用成功时,返回请求的唯一标识符 `requestId`。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-9]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## getPlaySrc [2/2] [#getplaysrc-22]
获取当前播放的音乐资源的标识符或 URL。
```java
@Override String getPlaySrc();
```
你需要在打开音乐资源后调用此方法:
- 如果使用 `open(Uri uri, long startPos)` 打开音乐资源,该方法返回音乐资源的标识符(`songCode`)。
- 如果使用 `open(String url, long startPos)` 打开音乐资源,该方法返回音乐资源的 URL。
### 返回值 [#返回值-9]
- 方法调用成功时,返回音乐资源的标识符或 URL。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-10]
- [IAgoraMusicPlayer](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer)
## getSongSimpleInfo [#getsongsimpleinfo]
检索特定音乐资源的详细信息。
```java
public abstract String getSongSimpleInfo(long songCode);
```
在调用该方法前,你需要先获取目标音乐资源的标识符。你可以通过调用 `getMusicCollectionByMusicChartId` 或 `searchMusic` 方法获取音乐资源,并通过触发的 [onMusicCollectionResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调获取音乐资源标识符(`songCode`)。
:::note
注: 成功调用该方法后,SDK 会触发 [onSongSimpleInfoResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) 回调,报告音乐资源的详细信息。
:::
### 参数 [#参数-5]
音乐资源的标识符,用于指定要查询的音乐资源。
### 返回值 [#返回值-10]
- 方法调用成功时,返回唯一标识此次请求的 `requestId`。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-11]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## initialize [#initialize]
初始化 [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)。
```java
public abstract int initialize(MusicContentCenterConfiguration configuration);
```
在调用 [initialize](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_initialize_imusiccontentcenter) 方法前,必须先进行初始化,才能调用其他方法。
### 参数 [#参数-6]
[IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter) 的配置参数。详见 [MusicContentCenterConfiguration](/zh-CN/api-reference/rtc/android/class-musiccontentcenterconfiguration)。
### 返回值 [#返回值-11]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-12]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## isPreloaded [#ispreloaded]
检查指定音乐资源是否已预加载。
```java
public abstract int isPreloaded(long songCode);
```
该方法为同步调用。
### 参数 [#参数-7]
音乐资源的标识符。
### 返回值 [#返回值-12]
- 0:方法调用成功,音乐资源已预加载。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-13]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## open [2/2] [#open-22]
通过 URL 打开音乐资源。
```java
int open(String url, long startPos)
```
调用该方法会触发 [onPlayerStateChanged](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) 回调。在收到播放状态为 `OPEN_COMPLETED` 的上报后,你可以调用 [play](/zh-CN/api-reference/rtc/android/play/rte-player#api_player_play_player) 方法播放媒体文件。
:::note
注: 如果你要打开的音乐资源受数字版权保护,必须使用此方法打开。对于不受数字版权保护的音乐资源,你可以选择使用此方法,或使用 `open` 方法打开。
:::
### 相关回调 [#相关回调-3]
调用该方法会触发 [onPlayerStateChanged](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) 回调。
### 参数 [#参数-8]
音乐资源的路径,支持本地文件和在线文件。
播放起始位置,单位为毫秒。(默认值为 0。)
### 返回值 [#返回值-13]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。详见 `错误码` 获取详细信息和排查建议。
### 所属接口类 [#所属接口类-14]
- [IAgoraMusicPlayer](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer)
## open [1/2] [#open-12]
通过资源 ID 打开音乐资源。
```java
int open(long songCode, long startPos);
```
调用该方法后,将触发 [onPlayerStateChanged](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) 回调。当你收到 `OPEN_COMPLETED` 状态后,可以调用 [play](/zh-CN/api-reference/rtc/android/play/rte-player#api_player_play_player) 方法播放媒体文件。
:::note
注: 如果要打开的音乐资源受数字版权管理保护,必须使用该方法。对于未受数字版权管理保护的音乐资源,可以使用该方法或 `open` 方法(参数为 `String url, long startPos`)。
:::
### 相关回调 [#相关回调-4]
调用该方法后,将触发 [onPlayerStateChanged](/zh-CN/api-reference/rtc/android/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) 回调。
### 参数 [#参数-9]
音乐资源的资源 ID,用于标识音乐。
起始播放位置,单位为毫秒。(默认值为 0)
### 返回值 [#返回值-14]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-15]
- [IAgoraMusicPlayer](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer)
## preload [1/2] [#preload-12]
预加载音乐资源。
```java
public abstract int preload(long songCode, String jsonOption)
```
:::error[废弃]
该方法已废弃,请改用 [preload [2/2]](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_preload2)。
:::
调用成功后,SDK 会触发 [onPreLoadEvent](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 回调报告预加载事件。在调用该方法前,你需要先调用 `getMusicCollectionByMusicChartId` 或 `searchMusic` 获取音乐资源,并从 [onMusicCollectionResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调中获取资源标识符(`songCode`)。
:::note
注: 销毁 [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) 对象前,请确保在收到 [onPreLoadEvent](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 回调后调用 [destroy [2/2]](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_destroy1) 方法。
:::
### 参数 [#参数-10]
音乐资源的标识符。
扩展的 JSON 字段。声网会根据你在 `sceneType` 字段中设置的应用场景计费,不同场景的计费标准不同,详见计费文档。
- 1:直播场景:在线 K 歌房和背景音乐播放。
- 2:直播场景:背景音乐播放。
- 3:(默认)声动语聊场景:在线 K 歌房。
- 4:声动语聊场景:背景音乐播放。
- 5:VR 场景:在线 K 歌房和背景音乐播放。
如果你需要切换到其他场景,必须重新调用该方法并在该字段中传入新的 `sceneType` 值。示例:`{"sceneType":1}`。
### 返回值 [#返回值-15]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-16]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## preload [2/2] [#preload-22]
预加载版权音乐资源。
```java
public abstract String preload(long songCode);
```
成功调用该方法后,SDK 会触发 [onPreLoadEvent](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 回调,报告预加载事件。在调用该方法前,你需要先调用 `getMusicCollectionByMusicChartId` 或 `searchMusic` 获取你想播放的版权音乐资源,并通过这些方法触发的 [onMusicCollectionResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调获取音乐资源标识符(`songCode`)。
:::note
注: 销毁 [RtcEngine](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengine) 对象前,请确保在收到 [onPreLoadEvent](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 回调后再调用 [destroy [2/2]](/zh-CN/api-reference/rtc/android/initialize#api_irtcengine_destroy1) 方法。
:::
### 参数 [#参数-11]
版权音乐资源的标识符。
### 返回值 [#返回值-16]
- 方法调用成功时,返回请求的唯一标识符 `requestId`。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-17]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## registerEventHandler [#registereventhandler]
注册版权音乐内容中心的回调事件。
```java
public abstract int registerEventHandler(IMusicContentCenterEventHandler eventHandler);
```
### 参数 [#参数-12]
要注册的回调事件。详见 [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcentereventhandler)。
### 返回值 [#返回值-17]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-18]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## removeCache [#removecache]
删除已缓存的音乐资源。
```java
public abstract int removeCache(long songCode);
```
若需删除多个音乐资源,可多次调用此方法。
:::note
注: [removeCache](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_removecache) 不会删除当前正在播放的已缓存音乐资源。
:::
### 参数 [#参数-13]
要删除的音乐资源的标识符。
### 返回值 [#返回值-18]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-19]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## renewToken [#renewtoken]
更新 Token。
```java
public abstract int renewToken(String token);
```
当用于鉴权的 Token 即将过期或已经过期时,可以调用该方法传入新生成的 Token。
### 参数 [#参数-14]
新生成的 Token。
### 返回值 [#返回值-19]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-20]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## searchMusic [1/2] [#searchmusic-12]
搜索音乐资源。
```java
public String searchMusic(String keyword, int page, int pageSize)
```
调用该方法后,SDK 会触发 [onMusicCollectionResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调,返回检索到的音乐资源列表。
### 参数 [#参数-15]
搜索关键词。支持按歌曲标题或艺术家名称搜索。
要获取的音乐资源列表的页码。
每页返回的最大音乐资源数量,最大值为 50。
### 返回值 [#返回值-20]
- 方法调用成功时,返回唯一标识该请求的 `requestId`。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-21]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## searchMusic [2/2] [#searchmusic-22]
搜索音乐资源。
```java
public abstract String searchMusic(String keyword, int page, int pageSize, String jsonOption);
```
### 相关回调 [#相关回调-5]
成功调用该方法后,SDK 会触发 [onMusicCollectionResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调报告检索到的音乐资源列表。
### 参数 [#参数-16]
搜索关键词。支持按歌曲名称或歌手名称搜索。
要获取的音乐资源列表的目标页码。
每页显示的最大音乐资源数量。最大值为 50。
可选的 JSON 扩展字段,默认为 `null`。你可以使用该字段筛选所需的音乐资源。目前支持以下筛选条件:
- `pitchType`:是否支持评分。
- 1:支持评分的音乐资源。
- 2:不支持评分的音乐资源。
- `needHighPart`:是否需要副歌片段。
- true:需要副歌片段。
- false:不需要副歌片段。
### 返回值 [#返回值-21]
- 方法调用成功时,返回唯一标识该请求的 `requestId`。
- 方法调用失败,返回空字符串。
### 所属接口类 [#所属接口类-22]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## setPlayMode [#setplaymode]
设置音乐曲目的播放模式。
```java
int setPlayMode(MusicPlayMode mode);
```
如果你未调用该方法设置播放模式,默认播放人声伴奏;如果音乐资源不包含人声伴奏,则播放原唱。
:::note
注: 你可以通过 [onMusicCollectionResult](/zh-CN/api-reference/rtc/android/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调获取音乐资源的详细信息,并使用该回调中的 `list` 参数查看该版权音乐支持的播放模式。
:::
### 适用场景 [#适用场景]
在在线 K 歌或才艺展示等娱乐场景中,如果你需要播放由声网内容中心提供的版权音乐,可以调用该方法设置播放模式。
### 调用时机 [#调用时机-1]
你必须在调用 [createMusicPlayer](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_createmusicplayer) 方法之后调用该方法。
### 参数 [#参数-17]
播放模式,详见 [MusicPlayMode](/zh-CN/api-reference/rtc/android/enum-musicplaymode)。
### 返回值 [#返回值-22]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:参数无效,请重新设置参数。
### 所属接口类 [#所属接口类-23]
- [IAgoraMusicPlayer](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer)
## stop [2/2] [#stop-22]
停止播放音乐资源。
```java
@Override int stop();
```
### 返回值 [#返回值-23]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-24]
- [IAgoraMusicPlayer](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusicplayer)
## unregisterEventHandler [#unregistereventhandler]
取消注册版权音乐内容中心的事件回调。
```java
public abstract int unregisterEventHandler();
```
### 返回值 [#返回值-24]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-25]
- [IAgoraMusicContentCenter](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcenter)
## onLyricResult [#onlyricresult]
歌词下载链接回调。
```java
@CalledByNative void onLyricResult(String requestId, long songCode, String lyricUrl, int reason);
```
调用 [getLyric](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_getlyric) 后,SDK 会触发该回调。
### 触发时机 [#触发时机]
该回调在调用 [getLyric](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_getlyric) 方法后被触发。
### 参数 [#参数-18]
请求 ID,用于唯一标识该请求。
音乐资源的编号,用于标识音乐资源。
歌词的下载链接。
来自版权音乐内容中心的请求状态码:
- `MUSIC_CONTENT_CENTER_STATE_REASON_OK` (0):请求成功。
- `MUSIC_CONTENT_CENTER_STATE_REASON_ERROR` (1):通用错误,无具体原因。
- `MUSIC_CONTENT_CENTER_STATE_REASON_GATEWAY` (2):网关错误。可能原因包括:
- 当前临时 Token 已过期。请重新生成 Token。
- 提供的 Token 无效。请确保使用的是 RTM Token。
- 网络错误。请检查网络连接。
- `MUSIC_CONTENT_CENTER_STATE_REASON_PERMISSION_AND_RESOURCE` (3):权限错误或音乐资源不存在。请确保项目已启用版权音乐内容中心权限。如有疑问,请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_INTERNAL_DATA_PARSE` (4):内部数据解析错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_MUSIC_LOADING` (5):加载音乐资源时发生错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_MUSIC_DECRYPTION` (6):解密音乐资源时发生错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_HTTP_INTERNAL` (7):HTTP 内部错误。请稍后重试。
### 所属接口类 [#所属接口类-26]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcentereventhandler)
## onMusicChartsResult [#onmusicchartsresult]
获取音乐排行榜后的回调。
```java
@CalledByNative void onMusicChartsResult(String requestId, MusicChartInfo[] list, int reason);
```
该回调在调用 [getMusicCharts](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_getmusiccharts) 后被触发。
### 触发时机 [#触发时机-1]
该回调在调用 [getMusicCharts](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_getmusiccharts) 方法后被触发。
### 参数 [#参数-19]
请求 ID,用于标识此次请求的唯一标识符。
当前可播放的音乐排行榜列表,详见 [MusicChartInfo](/zh-CN/api-reference/rtc/android/class-musicchartinfo)。
来自音乐内容中心的请求状态码:
- `MUSIC_CONTENT_CENTER_STATE_REASON_OK` (0):请求成功。
- `MUSIC_CONTENT_CENTER_STATE_REASON_ERROR` (1):通用错误,无具体原因。
- `MUSIC_CONTENT_CENTER_STATE_REASON_GATEWAY` (2):网关错误。可能原因包括:
- 当前 token 已过期。请重新生成 token。
- 提供的 token 无效。请确保使用的是 RTM token。
- 网络错误。请检查网络连接。
- `MUSIC_CONTENT_CENTER_STATE_REASON_PERMISSION_AND_RESOURCE` (3):权限错误或未找到音乐资源。请确保项目已启用访问声网音乐内容中心。如有问题,请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_INTERNAL_DATA_PARSE` (4):内部数据解析错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_MUSIC_LOADING` (5):加载音乐资源时发生错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_MUSIC_DECRYPTION` (6):解密音乐资源时发生错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_HTTP_INTERNAL` (7):内部 HTTP 错误。请稍后重试。
### 所属接口类 [#所属接口类-27]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcentereventhandler)
## onMusicCollectionResult [#onmusiccollectionresult]
获取音乐资源列表的回调。
```java
void onMusicCollectionResult(String requestId, int page, int pageSize, int total, Music[] list, int reason)
```
该回调在调用 `getMusicCollectionByMusicChartId` 或 `searchMusic` 时触发。
### 参数 [#参数-20]
请求 ID,用于唯一标识该请求。
当前页码,从 1 开始。
每页最多返回的音乐资源数量,最大为 50。
音乐资源列表中的总资源数。
音乐资源列表的详细信息,详见 [Music](/zh-CN/api-reference/rtc/android/class-music)。
来自声网音乐内容中心的请求状态码:
- `MUSIC_CONTENT_CENTER_STATE_REASON_OK (0)`:请求成功。
- `MUSIC_CONTENT_CENTER_STATE_REASON_ERROR (1)`:通用错误,无具体归因。
- `MUSIC_CONTENT_CENTER_STATE_REASON_GATEWAY (2)`:网关错误。可能原因包括:
- 当前临时 Token 已过期。请重新生成临时 Token。
- 提供的临时 Token 无效。请确保你使用的是 RTM Token。
- 网络错误。请检查你的网络连接。
- `MUSIC_CONTENT_CENTER_STATE_REASON_PERMISSION_AND_RESOURCE (3)`:权限错误或未找到音乐资源。请确保你的项目已启用访问声网音乐内容中心的权限。如有问题,请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_INTERNAL_DATA_PARSE (4)`:内部数据解析错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_MUSIC_LOADING (5)`:加载音乐资源时发生错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_MUSIC_DECRYPTION (6)`:解密音乐资源时发生错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_HTTP_INTERNAL (7)`:HTTP 内部错误。请稍后重试。
### 所属接口类 [#所属接口类-28]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcentereventhandler)
## onPreLoadEvent [#onpreloadevent]
预加载音乐资源事件的回调。
```java
void onPreLoadEvent(String requestId, long songCode, int percent, String lyricUrl, int state, int reason)
```
调用 `preload` 方法预加载音乐资源后,SDK 会触发该回调。
### 触发时机 [#触发时机-2]
该回调在调用 `preload` 方法后被触发。
### 参数 [#参数-21]
请求 ID,用于唯一标识该请求。
音乐资源的 ID,用于标识一个音乐资源。
音乐资源的当前加载进度,取值范围为 [0, 100]。
歌词的下载地址。
音乐资源的当前加载状态:
- 0:加载完成。
- 1:加载失败。
- 2:加载中。
来自 Music Content Center 的请求状态码:
- `MUSIC_CONTENT_CENTER_STATE_REASON_OK` (0):请求成功。
- `MUSIC_CONTENT_CENTER_STATE_REASON_ERROR` (1):通用错误,无具体归因。
- `MUSIC_CONTENT_CENTER_STATE_REASON_GATEWAY` (2):网关错误。可能原因包括:
- 当前临时 Token 已过期,请重新生成 Token。
- 提供的 Token 无效,请确保使用的是 Token。
- 网络错误,请检查网络连接。
- `MUSIC_CONTENT_CENTER_STATE_REASON_PERMISSION_AND_RESOURCE` (3):权限错误或音乐资源不存在。请确保项目已启用 Music Content Center 访问权限。如有问题请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_INTERNAL_DATA_PARSE` (4):内部数据解析错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_MUSIC_LOADING` (5):加载音乐资源时发生错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_MUSIC_DECRYPTION` (6):解密音乐资源时发生错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_HTTP_INTERNAL` (7):HTTP 内部错误。请稍后重试。
### 所属接口类 [#所属接口类-29]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcentereventhandler)
## onSongSimpleInfoResult [#onsongsimpleinforesult]
获取音乐资源详细信息的回调。
```java
void onSongSimpleInfoResult(String requestId, long songCode, String simpleInfo, int reason);
```
### 触发时机 [#触发时机-3]
该回调在调用 [getSongSimpleInfo](/zh-CN/api-reference/rtc/android/play/drm#api_imusiccontentcenter_getsongsimpleinfo) 后被触发。
### 参数 [#参数-22]
请求 ID,用于标识此次请求的唯一标识符。
音乐资源的标识符。
音乐资源的相关信息,包括:
- 副歌片段的起始和结束时间(毫秒)。
- 副歌歌词的下载链接。
- 副歌片段的时长(毫秒)。
- 歌曲标题。
- 艺术家名称。
来自音乐内容中心的请求状态码:
- `MUSIC_CONTENT_CENTER_STATE_REASON_OK` (0):请求成功。
- `MUSIC_CONTENT_CENTER_STATE_REASON_ERROR` (1):通用错误,无具体原因。
- `MUSIC_CONTENT_CENTER_STATE_REASON_GATEWAY` (2):网关错误。可能原因包括:
- 当前临时 Token 已过期,请生成新的 Token。
- 提供的 Token 无效,请确保使用的是 RTM Token。
- 网络错误,请检查网络连接。
- `MUSIC_CONTENT_CENTER_STATE_REASON_PERMISSION_AND_RESOURCE` (3):权限错误或音乐资源不存在。请确保项目已启用音乐内容中心权限。如有问题,请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_INTERNAL_DATA_PARSE` (4):内部数据解析错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_MUSIC_LOADING` (5):加载音乐资源时发生错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_MUSIC_DECRYPTION` (6):解密音乐资源时发生错误。请[联系技术支持](https://ticket.shengwang.cn/)。
- `MUSIC_CONTENT_CENTER_STATE_REASON_HTTP_INTERNAL` (7):内部 HTTP 错误。请稍后重试。
### 所属接口类 [#所属接口类-30]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_imusiccontentcentereventhandler)