# 版权音乐 (/zh-CN/api-reference/rtc/unreal-cpp/play/drm)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## createMusicPlayer [#createmusicplayer]
创建音乐播放器。
```cpp
virtual agora_refptr createMusicPlayer() = 0;
```
### 详情 [#详情]
如果你需要播放音乐内容中心的音乐资源,你需要先调用该方法来创建一个音乐播放器。
### 返回值 [#返回值]
- 方法调用成功:返回 [IMusicPlayer](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusicplayer) 对象。
- 方法调用失败:返回空指针。
### 所属接口类 [#所属接口类]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## destroyMusicPlayer [#destroymusicplayer]
销毁音乐播放器对象。
```cpp
virtual int destroyMusicPlayer(agora_refptr music_player) = 0;
```
当你不再需要使用音乐播放器时,你可以调用该方法来销毁音乐播放器对象。销毁之后如果需要重新使用音乐播放器,需要调用 [createMusicPlayer](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_createmusicplayer) 重新创建一个音乐播放器对象。
### 调用时机 [#调用时机]
该方法在加入频道前后均可调用,但请确保在 IRtcEngine 的 [Release](/zh-CN/api-reference/rtc/unreal-cpp/initialize#api_irtcengine_release) 方法前调用。
### 调用限制 [#调用限制]
无。
### 参数 [#参数]
[IMusicPlayer](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusicplayer) 对象。
### 返回值 [#返回值-1]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## getCaches [#getcaches]
获取已缓存的音乐资源信息。
```cpp
virtual int getCaches(MusicCacheInfo *cacheInfo, int32_t* cacheInfoSize) = 0;
```
### 详情 [#详情-1]
调用该方法前,你需要预先分配一定大小的内存空间用来存储缓存音乐资源的信息。如果你需要设置可缓存的音乐资源数量,可通过 [initialize](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_initialize) 的 configuration 来设置。
当你不再需要使用已缓存的音乐资源时,你需要及时释放内存以防止内存泄漏。
### 参数 [#参数-1]
输出参数,指向用于存储已缓存音乐资源的内存缓冲区的指针。
输入和输出参数。
- 输入值:cacheInfo 数组的长度,即你所分配的 [MusicCacheInfo](/zh-CN/api-reference/rtc/unreal-cpp/class-musiccacheinfo) 结构体的数量。
- 输出值:方法执行完毕后输出的 MusicCacheInfo 结构体的数量。
### 返回值 [#返回值-2]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-2]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## getCount [2/2] [#getcount-22]
获取本次请求的音乐数量。
```cpp
virtual int getCount() = 0;
```
### 详情 [#详情-2]
### 返回值 [#返回值-3]
本次请求的音乐数量。
## get [#get]
获取音乐榜单的详细信息。
```cpp
virtual MusicChartInfo* get(int index) = 0;
```
### 详情 [#详情-3]
### 参数 [#参数-2]
[MusicChartInfo](/zh-CN/api-reference/rtc/unreal-cpp/class-musicchartinfo) 数组的索引。
### 返回值 [#返回值-4]
[MusicChartInfo](/zh-CN/api-reference/rtc/unreal-cpp/class-musicchartinfo),包含音乐榜单的详细信息。
## getInternalSongCode [#getinternalsongcode]
创建音乐资源的副歌片段编号。
```cpp
virtual int getInternalSongCode(int64_t songCode, const char* jsonOption, int64_t& internalSongCode) = 0;
```
### 适用场景 [#适用场景]
当你需要播放某一音乐资源的副歌片段前,你需要调用此方法,通过 jsonOption 参数和该音乐资源的 songCode 来为该音乐资源的副歌片段创建一个编号,作为该资源的唯一标识。当你获取到该片段的编号后,在你调用相应方法打开、预加载、移除该资源时,将该内部歌曲编号传入 songCode 参数。
### 参数 [#参数-3]
音乐资源编号,用于标识音乐资源。你可以通过调用 [getMusicCollectionWithMusicChartId](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_getmusiccollectionbymusicchartid) 或 [searchMusic](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_searchmusic) 方法来获取音乐资源,并通过由此触发的 [onMusicCollectionResult](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调获取音乐资源的编号(songCode)。
扩展 JSON 字段,默认为 NULL。目前支持传入下列值:
| Key 值 | Value 值 | 示例 |
| --- | --- | --- |
| sceneType | [api-center-table-0 details](#table-slot-api-center-table-0) | \\\{"sceneType"\:1\\\} |
| highPart | 副歌片段的索引。你可以从 [onMusicCollectionResult](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调中获取副歌片段的索引然后传值。索引序号从 0 开始。 | \\\{"format": \\\{"highpart": 0\\\}\\\} |
**api-center-table-0 details**
场景类型:
- 1:直播场景:K 歌及背景音乐播放。
- 2:直播场景:背景音乐播放。
- 3:(默认)语聊场景:K 歌。
- 4:语聊场景:背景音乐播放。
- 5:VR 场景:K 歌及背景音乐播放。
:::note
注: 声网会根据你在 sceneType 传入的应用场景进行收费。不同的应用场景对应不同的费率,你可以参考 [计费说明](/zh-CN/solutions/online-ktv/online-ktv-sdk/reference/billing) 查看详细的计费。如果需要切换到不同场景,需要重新调用此方法并传入 sceneType 的值。
:::
输出参数,音乐资源的内部歌曲编号。
### 返回值 [#返回值-5]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## getLyric [#getlyric]
获取音乐资源的歌词下载地址。
```cpp
virtual int getLyric(agora::util::AString& requestId, int64_t songCode, int32_t LyricType = 0) = 0;
```
### 详情 [#详情-4]
成功调用该方法后,SDK 会触发 [onLyricResult](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 回调报告歌词的下载地址。
### 参数 [#参数-4]
音乐资源的编号,用于标识音乐资源。
歌词类型:
- 0:xml 格式。
- 1:lrc 格式。
请求 ID。本次请求的唯一标识。
### 返回值 [#返回值-6]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-4]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## getMusic [#getmusic]
获取当前页面列表中音乐资源的详细信息。
```cpp
virtual Music* getMusic(int32_t index) = 0;
```
### 详情 [#详情-5]
### 参数 [#参数-5]
[Music](/zh-CN/api-reference/rtc/unreal-cpp/class-music) 数组的索引。
### 返回值 [#返回值-7]
一个 [Music](/zh-CN/api-reference/rtc/unreal-cpp/class-music) 实例。
## getMusicCharts [#getmusiccharts]
获取全部音乐榜单。
```cpp
virtual int getMusicCharts(agora::util::AString& requestId) = 0;
```
### 详情 [#详情-6]
当你调用该方法后,SDK 会触发 [onMusicChartsResult](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) 回调报告音乐榜单的详细信息。
### 参数 [#参数-6]
请求 ID。本次请求的唯一标识。
### 返回值 [#返回值-8]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-5]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## getMusicCollectionWithMusicChartId [#getmusiccollectionwithmusicchartid]
通过音乐榜单的 ID 获取指定榜单的音乐资源列表。
```cpp
virtual int getMusicCollectionByMusicChartId(agora::util::AString& requestId, int32_t musicChartId, int32_t page, int32_t pageSize, const char* jsonOption = nullptr) = 0;
```
### 详情 [#详情-7]
成功调用该方法后,SDK 会触发 [onMusicCollectionResult](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调报告榜单中音乐资源列表的详细信息。
### 参数 [#参数-7]
请求 ID。本次请求的唯一标识。
音乐榜单的 ID,可以通过 [onMusicChartsResult](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) 回调获取。你也可以通过 RESTful API 来[获取曲库所有歌曲列表](/zh-CN/api-reference/online-ktv/android/ktv-scenario/api/music-content-center#获取曲库所有歌曲列表)或[获取增量歌曲列表](/zh-CN/api-reference/online-ktv/android/ktv-scenario/api/music-content-center#获取增量歌曲列表)。
当前页面编号,默认从 1 开始。
当前音乐资源列表的总页面数量,最大值为 50。
扩展 JSON 字段,默认为 NULL。你可以通过该字段来筛选出你需要的音乐资源,目前支持筛选可打分的音乐资源及音乐资源的副歌片段:
| Key 值 | Value 值 | 示例 |
| --- | --- | --- |
| pitchType | [api-center-table-1 details](#table-slot-api-center-table-1) | \\\{"pitchType"\:1\\\} |
| needHighPart | [api-center-table-2 details](#table-slot-api-center-table-2) | \\\{"needHighPart"\:true\\\} |
**api-center-table-1 details**
是否支持打分:
- 1:支持打分的音乐资源。
- 2:不支持打分的音乐资源。
**api-center-table-2 details**
是否需要副歌片段资源:
- `true`:需要副歌片段资源。
- `false`:不需要副歌片段资源。
### 返回值 [#返回值-9]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-6]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## getPage [#getpage]
获取音乐资源列表当前页的页码。
```cpp
virtual int getPage() = 0;
```
### 详情 [#详情-8]
### 返回值 [#返回值-10]
当前页的页码。
## getPageSize [#getpagesize]
获取 SDK 实际返回的音乐资源数量。
```cpp
virtual int getPageSize() = 0;
```
### 详情 [#详情-9]
### 返回值 [#返回值-11]
SDK 实际返回的音乐资源数量。
## getTotal [#gettotal]
获取列表内音乐资源的总数量。
```cpp
virtual int getTotal() = 0;
```
### 详情 [#详情-10]
### 返回值 [#返回值-12]
列表内音乐资源的总数量。
## getSongSimpleInfo [#getsongsimpleinfo]
获取某一音乐资源的详细信息。
```cpp
virtual int getSongSimpleInfo(agora::util::AString& requestId, int64_t songCode) = 0;
```
### 详情 [#详情-11]
在调用该方法前,你需要先获取到对应的音乐资源的编号。你可以通过调用 [getMusicCollectionWithMusicChartId](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_getmusiccollectionbymusicchartid) 或 [searchMusic](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_searchmusic) 方法来获取音乐资源,并通过由此触发的 [onMusicCollectionResult](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调获取音乐资源的编号(songCode)。
当你调用该方法后,SDK 会触发 [onSongSimpleInfoResult](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) 回调报告音乐资源的详细信息。
### 参数 [#参数-8]
音乐资源的编号,用于标识音乐资源。
请求 ID。本次请求的唯一标识。
### 返回值 [#返回值-13]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-7]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## initialize [#initialize]
初始化 [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)。
```cpp
virtual int initialize(const MusicContentCenterConfiguration & configuration) = 0;
```
### 详情 [#详情-12]
在调用 [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter) 类下的其他方法前,你需要先调用该方法初始化 IMusicContentCenter。
### 参数 [#参数-9]
IMusicContentCenter 的设置,详见 [MusicContentCenterConfiguration](/zh-CN/api-reference/rtc/unreal-cpp/class-musiccontentcenterconfiguration)。
### 返回值 [#返回值-14]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-8]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## isPreloaded [#ispreloaded]
检测音乐资源是否已被预加载。
```cpp
virtual int isPreloaded(int64_t songCode) = 0;
```
### 详情 [#详情-13]
该方法为同步调用。如需预加载新的音乐资源,可调用 [preload [2/2]](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusicontentcenter_preload2)。
### 参数 [#参数-10]
音乐资源的编号,用于标识一个音乐资源。
### 返回值 [#返回值-15]
- 0: 方法调用成功,该音乐资源已被预加载。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-9]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## preload [1/2] [#preload-12]
预加载音乐资源。
```cpp
virtual int preload(int64_t songCode, const char* jsonOption = nullptr) = 0;
```
### 详情 [#详情-14]
你可以调用该方法预先加载需要播放的音乐资源。成功调用该方法后,SDK 会触发 [onPreLoadEvent](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent) 回调报告预加载音乐资源的事件。
在调用该方法来预加载音乐资源之前,你需要调用 [getMusicCollectionWithMusicChartId](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_getmusiccollectionbymusicchartid) 或 [searchMusic](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_searchmusic) 方法来获取你需要播放的音乐资源,并通过由此触发的 [onMusicCollectionResult](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调获取音乐资源的编号(songCode)。
:::caution
注意: 如需销毁 [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) 对象,请在收到 [onPreLoadEvent](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent) 回调后,再调用 [Release](/zh-CN/api-reference/rtc/unreal-cpp/initialize#api_irtcengine_release) 方法。
:::
### 参数 [#参数-11]
音乐资源的编号,用于标识音乐资源。
扩展 JSON 字段。
声网会根据你在场景字段(sceneType)传入的应用场景进行收费。不同的应用场景对应不同的费率,你可以参考 [计费说明](/zh-CN/solutions/online-ktv/online-ktv-sdk/reference/billing) 查看详细的计费。
- 1:直播场景:K 歌及背景音乐播放。
- 2:直播场景:背景音乐播放。
- 3:(默认)语聊场景:K 歌。
- 4:语聊场景:背景音乐播放。
- 5:VR 场景:K 歌及背景音乐播放。
如果需要切换到不同场景,需要重新调用此方法并在该字段中传入 sceneType 的值。
示例:`{"sceneType":1}`
### 返回值 [#返回值-16]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-10]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## preload [2/2] [#preload-22]
预加载音乐资源。
```cpp
virtual int preload(agora::util::AString& requestId, int64_t songCode) = 0;
```
### 详情 [#详情-15]
你可以调用该方法预先加载需要播放的音乐资源。成功调用该方法后,SDK 会触发 [onPreLoadEvent](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent) 回调报告预加载音乐资源的事件。
在调用该方法来预加载音乐资源之前,你需要调用 [getMusicCollectionWithMusicChartId](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_getmusiccollectionbymusicchartid) 或 [searchMusic](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_searchmusic) 方法来获取你需要播放的音乐资源,并通过由此触发的 [onMusicCollectionResult](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调获取音乐资源的编号(songCode)。
:::caution
注意: 如需销毁 [IRtcEngine](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_irtcengine) 对象,请在收到 [onPreLoadEvent](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent) 回调后,再调用 [Release](/zh-CN/api-reference/rtc/unreal-cpp/initialize#api_irtcengine_release) 方法。
:::
### 参数 [#参数-12]
音乐资源的编号,用于标识音乐资源。
输出参数,请求 ID。本次请求的唯一标识。
### 返回值 [#返回值-17]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-11]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## registerEventHandler [#registereventhandler]
注册音乐内容中心回调事件。
```cpp
virtual int registerEventHandler(IMusicContentCenterEventHandler* eventHandler) = 0;
```
### 详情 [#详情-16]
### 参数 [#参数-13]
待注册的回调事件,详见 [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcentereventhandler)。
### 返回值 [#返回值-18]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-12]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## release [#release]
释放音乐内容中心所占用的所有资源。
```cpp
virtual void release() = 0;
```
### 详情 [#详情-17]
该方法需要在 IRtcEngine 的 [Release](/zh-CN/api-reference/rtc/unreal-cpp/initialize#api_irtcengine_release) 方法前调用。
### 所属接口类 [#所属接口类-13]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## removeCache [#removecache]
删除已缓存的音乐资源。
```cpp
virtual int removeCache(int64_t songCode) = 0;
```
### 详情 [#详情-18]
你可以调用该方法删除某一已缓存的音乐资源,如需删除多个音乐资源,你可以多次调用该方法。
:::note
注: 该方法不会删除正在播放中的已缓存音乐资源。
:::
### 参数 [#参数-14]
待删除的音乐资源的编号。
### 返回值 [#返回值-19]
- 0: 方法调用成功,音乐资源已删除。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-14]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## renewToken [#renewtoken]
更新 Token。
```cpp
virtual int renewToken(const char* token) = 0;
```
### 详情 [#详情-19]
当你用于鉴权的 Token 快要过期或已过期时,你可以调用该方法来传入新生成的 Token。
### 参数 [#参数-15]
新的 Token。
### 返回值 [#返回值-20]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-15]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## searchMusic [#searchmusic]
搜索音乐资源。
```cpp
virtual int searchMusic(agora::util::AString& requestId, const char* keyWord, int32_t page, int32_t pageSize, const char* jsonOption = nullptr) = 0;
```
### 详情 [#详情-20]
成功调用该方法后,SDK 会触发 [onMusicCollectionResult](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调报告检索到的音乐资源列表。
### 参数 [#参数-16]
搜索关键词,支持歌曲名、歌手搜索。
想要获取的音乐资源列表的目标页编号。
每页所展示的音乐资源的最大数量,最大值为 50。
扩展 JSON 字段,默认为 NULL。你可以通过该字段来筛选出你需要的音乐资源,目前支持筛选可打分的音乐资源及音乐资源的副歌片段:
| Key 值 | Value 值 | 示例 |
| --- | --- | --- |
| pitchType | [api-center-table-3 details](#table-slot-api-center-table-3) | \\\{"pitchType"\:1\\\} |
| needHighPart | [api-center-table-4 details](#table-slot-api-center-table-4) | \\\{"needHighPart"\:true\\\} |
**api-center-table-3 details**
是否支持打分:
- 1:支持打分的音乐资源。
- 2:不支持打分的音乐资源。
**api-center-table-4 details**
是否需要副歌片段资源:
- `true`:需要副歌片段资源。
- `false`:不需要副歌片段资源。
请求 ID。本次请求的唯一标识。
### 返回值 [#返回值-21]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-16]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## setPlayMode [#setplaymode]
设置音乐资源的播放模式。
```cpp
virtual int setPlayMode(MusicPlayMode mode) = 0;
```
你可以调用该方法来设置启用原唱、伴奏或导唱。如不调用该方法进行设置,则默认播放伴奏;如果音乐资源没有伴奏,则播放原唱。
:::caution
注意: 你可以通过 [onMusicCollectionResult](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调获取音乐资源的详细信息,并可通过其中的 result 参数得知需播放的版权音乐所支持的播放类型。
:::
### 适用场景 [#适用场景-1]
在线 K 歌、秀场等娱乐场景下,如果你需要播放声网内容中心提供的版权音乐,你可以调用该方法来设置播放模式。
### 调用时机 [#调用时机-1]
该方法需要在 [createMusicPlayer](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_createmusicplayer) 之后调用。
### 调用限制 [#调用限制-1]
无。
### 参数 [#参数-17]
播放模式,详见 [MusicPlayMode](/zh-CN/api-reference/rtc/unreal-cpp/enum-musicplaymode)。
### 返回值 [#返回值-22]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2: 参数设置错误,请重新设置参数。
### 所属接口类 [#所属接口类-17]
- [IMusicPlayer](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusicplayer)
## unregisterEventHandler [#unregistereventhandler]
取消注册音乐内容中心事件回调。
```cpp
virtual int unregisterEventHandler() = 0;
```
### 详情 [#详情-21]
### 返回值 [#返回值-23]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-18]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcenter)
## onLyricResult [#onlyricresult]
歌词下载地址回调。
```cpp
virtual void onLyricResult(const char* requestId, int64_t songCode, const char* lyricUrl, MusicContentCenterStateReason reason) = 0;
```
### 详情 [#详情-22]
当你调用 [getLyric](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_getlyric) 获取指定歌曲的歌词下载地址后,SDK 会触发该回调。
### 参数 [#参数-18]
请求 ID。本次请求的唯一标识。
歌词的下载地址。
音乐内容中心的请求状态码,详见 [MusicContentCenterStateReason](/zh-CN/api-reference/rtc/unreal-cpp/enum-musiccontentcenterstatereason)。
### 所属接口类 [#所属接口类-19]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcentereventhandler)
## onMusicChartsResult [#onmusicchartsresult]
获取音乐榜单回调。
```cpp
virtual void onMusicChartsResult(const char* requestId, agora_refptr result, MusicContentCenterStateReason reason) = 0;
```
### 详情 [#详情-23]
当你调用 [getMusicCharts](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_getmusiccharts) 方法获取全部音乐榜单之后,SDK 会触发该回调。
### 参数 [#参数-19]
请求 ID。本次请求的唯一标识。
音乐内容中心的请求状态码,详见 [MusicContentCenterStateReason](/zh-CN/api-reference/rtc/unreal-cpp/enum-musiccontentcenterstatereason)。
当前可播放的音乐榜单列表。详见 [MusicChartInfo](/zh-CN/api-reference/rtc/unreal-cpp/class-musicchartinfo)[MusicChartCollection](/zh-CN/api-reference/rtc/unreal-cpp/class-musicchartcollection)。
### 所属接口类 [#所属接口类-20]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcentereventhandler)
## onMusicCollectionResult [#onmusiccollectionresult]
获取音乐资源列表回调。
```cpp
virtual void onMusicCollectionResult(const char* requestId, agora_refptr result, MusicContentCenterStateReason reason) = 0;
```
### 详情 [#详情-24]
当你调用 [getMusicCollectionWithMusicChartId](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_getmusiccollectionbymusicchartid) 方法来获取指定榜单的音乐资源列表或调用 [searchMusic](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_searchmusic) 来搜索音乐资源时,SDK 会触发此回调报告榜单中音乐资源列表的详细信息。
### 参数 [#参数-20]
请求 ID。本次请求的唯一标识。
音乐内容中心的请求状态码,详见 [MusicContentCenterStateReason](/zh-CN/api-reference/rtc/unreal-cpp/enum-musiccontentcenterstatereason)。
音乐资源列表的详细信息。详见 [MusicCollection](/zh-CN/api-reference/rtc/unreal-cpp/class-musiccollection)。
### 所属接口类 [#所属接口类-21]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcentereventhandler)
## onPreLoadEvent [#onpreloadevent]
报告预加载音乐资源的事件。
```cpp
virtual void onPreLoadEvent(const char* requestId, int64_t songCode, int percent, const char* lyricUrl, PreloadState state, MusicContentCenterStateReason reason) = 0;
```
### 详情 [#详情-25]
当你调用 [preload [1/2]](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusicontentcenter_preload) 或 [preload [2/2]](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusicontentcenter_preload2) 方法预加载音乐资源后,SDK 会触发该回调。
### 参数 [#参数-21]
请求 ID。本次请求的唯一标识。
音乐资源的编号,用于标识一个音乐资源。
音乐资源当前的加载进度,取值范围为 [0,100]。
歌词下载地址。
当前音乐资源的加载状态。详见 [PreloadState](/zh-CN/api-reference/rtc/unreal-cpp/enum-preloadstate)。
音乐内容中心的请求状态码,详见 [MusicContentCenterStateReason](/zh-CN/api-reference/rtc/unreal-cpp/enum-musiccontentcenterstatereason)。
### 所属接口类 [#所属接口类-22]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcentereventhandler)
## onSongSimpleInfoResult [#onsongsimpleinforesult]
音乐资源的详细信息回调。
```cpp
virtual void onSongSimpleInfoResult(const char* requestId, int64_t songCode, const char* simpleInfo, MusicContentCenterStateReason reason) = 0;
```
### 详情 [#详情-26]
当你调用 [getSongSimpleInfo](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_getsongsimpleinfo) 获取某一音乐资源的详细信息后,SDK 会触发该回调。
### 参数 [#参数-22]
请求 ID。本次请求的唯一标识。
音乐资源的编号,用于标识音乐资源。
音乐资源的相关信息,包含下列内容:
- 副歌片段的开始和结束的时间(ms)
- 副歌片段的歌词下载地址
- 副歌片段时长(ms)
- 歌曲名称
- 歌手名
音乐内容中心的请求状态码,详见 [MusicContentCenterStateReason](/zh-CN/api-reference/rtc/unreal-cpp/enum-musiccontentcenterstatereason)。
### 所属接口类 [#所属接口类-23]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusiccontentcentereventhandler)
## open [#open]
通过音乐资源编号打开音乐资源。
```cpp
virtual int open(int64_t songCode, int64_t startPos = 0) = 0;
```
### 详情 [#详情-27]
:::note
注: 如果你想要打开的音乐资源受数字版权保护,则需要调用此方法打开。对于不受数字版权保护的音乐资源,你可以选择通过调用此方法或 IMediaPlayer 类下的 [open](/zh-CN/api-reference/rtc/unreal-cpp/play/mediaplayer/mediaplayer-open#api_imediaplayer_open) 方法来打开。
:::
在调用此方法之前,请确保需要播放的音乐资源已加载完成。你可以调用 [isPreloaded](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#api_imusiccontentcenter_ispreloaded) 方法来检测音乐资源是否已被预加载,或通过 [onPreLoadEvent](/zh-CN/api-reference/rtc/unreal-cpp/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent) 回调得知。
调用该方法后会触发 [onPlayerSourceStateChanged](/zh-CN/api-reference/rtc/unreal-cpp/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) 回调。在收到报告播放状态为 PLAYER_STATE_OPEN_COMPLETED 后,你可以调用 [play](/zh-CN/api-reference/rtc/unreal-cpp/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 方法播放媒体文件。
### 参数 [#参数-23]
音乐资源的编号,用于标识音乐资源。
设置起始播放位置(毫秒),默认值为 0。
### 返回值 [#返回值-24]
- 0: 方法调用成功。
- < 0: 方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-24]
- [IMusicPlayer](/zh-CN/api-reference/rtc/unreal-cpp/rtc-interface-class#class_imusicplayer)