# 版权音乐 (/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
## createMusicPlayer [#createmusicplayer]
创建一个音乐播放器。
```cpp
virtual agora_refptr createMusicPlayer() = 0;
```
如果你需要播放来自声网 Music Content Center 的音乐资源,必须先调用 [createMusicPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_createmusicplayer) 创建一个音乐播放器。
### 返回值 [#返回值]
- 方法调用成功,返回一个 [IMusicPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusicplayer) 对象,详见 [IMusicPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusicplayer)。
- 方法调用失败,返回 NULL。
### 所属接口类 [#所属接口类]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## destroyMusicPlayer [#destroymusicplayer]
销毁音乐播放器对象。
```cpp
virtual int destroyMusicPlayer(agora_refptr music_player) = 0;
```
当你不再需要使用音乐播放器时,可以调用此方法销毁该对象。如果销毁后需要再次使用音乐播放器,请调用 [createMusicPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_createmusicplayer) 重新创建。
### 调用时机 [#调用时机]
该方法可以在加入频道前或加入频道后调用,但必须在调用 [release](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_release_imusiccontentcenter) 方法之前调用。
### 参数 [#参数]
音乐播放器对象。详见 [IMusicPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusicplayer)。
### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-1]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## get [#get]
获取指定音乐榜单的详细信息。
```cpp
virtual MusicChartInfo* get(int index) = 0;
```
### 参数 [#参数-1]
[MusicChartInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musicchartinfo) 数组中的索引。
### 返回值 [#返回值-2]
- 方法调用成功,返回 [MusicChartInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musicchartinfo) 实例,详见 [MusicChartInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musicchartinfo)。
- 方法调用失败,返回 NULL。
### 所属接口类 [#所属接口类-2]
- [MusicChartCollection](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_musicchartcollection)
## getCaches [#getcaches]
获取已缓存的音乐资源信息。
```cpp
virtual int getCaches(MusicCacheInfo *cacheInfo, int32_t* cacheInfoSize) = 0;
```
调用该方法前,需要预先分配内存用于存储已缓存音乐资源的信息。如果希望设置可缓存的音乐资源数量,可以通过 [initialize](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_initialize_imusiccontentcenter) 中的 `configuration` 参数进行配置。当不再需要这些缓存资源时,应及时释放内存以避免内存泄漏。
### 参数 [#参数-2]
输出参数,用于存储已缓存音乐资源信息的内存缓冲区指针。详见 [MusicCacheInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musiccacheinfo)。
输入和输出参数,表示 [MusicCacheInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musiccacheinfo) 数组的大小。
- 输入值:分配的 [MusicCacheInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musiccacheinfo) 结构体数量。
- 输出值:方法执行后返回的 [MusicCacheInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musiccacheinfo) 结构体数量。
### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-3]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## getCount [1/2] [#getcount-12]
获取当前请求中的音乐排行榜数量。
```cpp
virtual int getCount() = 0;
```
### 返回值 [#返回值-4]
方法调用成功,返回当前请求中的音乐排行榜数量。
### 所属接口类 [#所属接口类-4]
- [MusicChartCollection](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_musicchartcollection)
## getCount [2/2] [#getcount-22]
获取当前请求中的音乐项数量。
```cpp
virtual int getCount() = 0;
```
### 返回值 [#返回值-5]
方法调用成功,返回当前请求中的音乐项数量。
### 所属接口类 [#所属接口类-5]
- [MusicCollection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musiccollection)
## getInternalSongCode [#getinternalsongcode]
创建音乐资源副歌片段的内部歌曲编码。
```cpp
virtual int getInternalSongCode(int64_t songCode, const char* jsonOption, int64_t& internalSongCode) = 0;
```
在播放音乐资源的副歌片段前,需调用该方法,结合参数 `jsonOption` 和音乐资源的 `songCode` 创建副歌片段的内部歌曲编码。该编码作为资源的唯一标识。获取该编码后,在调用打开、预加载或移除资源的方法时,将其作为 `songCode` 参数传入。
### 参数 [#参数-3]
音乐资源的歌曲编码,用于标识资源。你可以通过调用 [getMusicCollectionByMusicChartId](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_getmusiccollectionbymusicchartid) 或 [searchMusic](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_searchmusic) 获取,并从这些方法触发的 [onMusicCollectionResult](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调中获取该编码。
扩展 JSON 字段,默认为 NULL。目前支持以下字段:
- sceneType:场景类型。1:直播场景,在线 K 歌房和背景音乐播放;2:直播场景,背景音乐播放;3:(默认)声动语聊场景,在线 K 歌房;4:声动语聊场景,背景音乐播放;5:VR 场景,在线 K 歌房和背景音乐播放。示例代码 `{"sceneType":1}`。
- highPart:副歌片段的索引,从 [onMusicCollectionResult](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调中获取,索引从 0 开始。示例代码 `{"format": {"highpart": 0}}`。
输出参数,音乐资源的内部歌曲编码。
### 返回值 [#返回值-6]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。详见错误码及其解决建议。
### 所属接口类 [#所属接口类-6]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## getLyric [#getlyric]
获取音乐资源歌词的下载链接。
```cpp
virtual int getLyric(agora::util::AString& requestId, int64_t songCode, int32_t lyricType = 0) = 0;
```
### 相关回调 [#相关回调]
调用该方法后,SDK 会触发 [onLyricResult](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onlyricresult) 回调报告歌词下载链接。
### 参数 [#参数-4]
请求 ID,用于唯一标识该请求。
音乐资源的 ID,用于标识音乐。
歌词类型:
- 0:XML 格式。
- 1:LRC 格式。
### 返回值 [#返回值-7]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-7]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## getMusic [#getmusic]
获取当前页面中指定音乐资源的详细信息。
```cpp
virtual Music* getMusic(int32_t index) = 0;
```
### 参数 [#参数-5]
[Music](/zh-CN/api-reference/rtc/cpp-all-platforms/class-music) 数组中的索引。
### 返回值 [#返回值-8]
- 方法调用成功,返回 [Music](/zh-CN/api-reference/rtc/cpp-all-platforms/class-music) 实例,详见 [Music](/zh-CN/api-reference/rtc/cpp-all-platforms/class-music)。
- 方法调用失败,返回 NULL。
### 所属接口类 [#所属接口类-8]
- [MusicCollection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musiccollection)
## getMusicCharts [#getmusiccharts]
获取所有音乐排行榜。
```cpp
virtual int getMusicCharts(agora::util::AString& requestId) = 0;
```
### 相关回调 [#相关回调-1]
成功调用该方法后,SDK 会触发 [onMusicChartsResult](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) 回调,报告音乐排行榜的详细信息。
### 参数 [#参数-6]
用于标识此次请求的唯一标识符。
### 返回值 [#返回值-9]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-9]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## getMusicCollectionByMusicChartId [#getmusiccollectionbymusicchartid]
获取指定音乐榜单 ID 的音乐资源列表。
```cpp
virtual int getMusicCollectionByMusicChartId(agora::util::AString& requestId, int32_t musicChartId, int32_t page, int32_t pageSize, const char* jsonOption = nullptr) = 0;
```
调用该方法后,SDK 会触发 [onMusicCollectionResult](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调,报告该榜单中的音乐资源详情。
### 参数 [#参数-7]
请求 ID,用于标识该请求的唯一标识符。
音乐榜单的 ID。你可以通过 [onMusicChartsResult](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onmusicchartsresult) 回调获取该 ID,或通过 RESTful API 获取完整音乐库列表或增量音乐列表。
当前页码,从 1 开始。
每页返回的音乐资源数量,最大值为 50。
扩展 JSON 字段,默认为 NULL。你可以使用该字段筛选所需的音乐资源。目前支持以下筛选项:
- `pitchType`:是否支持评分。
- 1:可评分音乐。
- 2:不可评分音乐。
- `needHighPart`:是否需要合唱片段。
- true:需要合唱片段。
- false:不需要合唱片段。
示例:
- `{ "pitchType": 1 }`
- `{ "needHighPart": true }`
### 返回值 [#返回值-10]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。请参见错误码文档获取详细信息和解决方案。
### 所属接口类 [#所属接口类-10]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## getPage [#getpage]
获取音乐资源列表当前的页码。
```cpp
virtual int getPage() = 0;
```
### 返回值 [#返回值-11]
方法调用成功,返回当前页码。
### 所属接口类 [#所属接口类-11]
- [MusicCollection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musiccollection)
## getPageSize [#getpagesize]
获取 SDK 实际返回的音乐资源数量。
```cpp
virtual int getPageSize() = 0;
```
### 返回值 [#返回值-12]
方法调用成功,返回 SDK 实际返回的音乐资源数量。
### 所属接口类 [#所属接口类-12]
- [MusicCollection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musiccollection)
## getSongSimpleInfo [#getsongsimpleinfo]
获取指定音乐资源的详细信息。
```cpp
virtual int getSongSimpleInfo(agora::util::AString& requestId, int64_t songCode) = 0;
```
调用该方法前,你需要先获取目标音乐资源的歌曲编号。你可以通过调用 [getMusicCollectionByMusicChartId](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_getmusiccollectionbymusicchartid) 或 [searchMusic](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_searchmusic) 方法,并从其触发的 [onMusicCollectionResult](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调中获取歌曲编号。调用该方法后,SDK 会触发 [onSongSimpleInfoResult](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) 回调,返回该音乐资源的详细信息。
### 相关回调 [#相关回调-2]
成功调用该方法后,SDK 会触发 [onSongSimpleInfoResult](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onsongsimpleinforesult) 回调,返回音乐资源的详细信息。
### 参数 [#参数-8]
请求 ID,用于唯一标识该请求。
音乐资源的歌曲编号,用于标识音乐。
### 返回值 [#返回值-13]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-13]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## getTotal [#gettotal]
获取音乐资源列表中的总数。
```cpp
virtual int getTotal() = 0;
```
### 返回值 [#返回值-14]
方法调用成功,返回音乐资源的总数。
### 所属接口类 [#所属接口类-14]
- [MusicCollection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musiccollection)
## initialize [#initialize]
初始化 [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)。
```cpp
virtual int initialize(const MusicContentCenterConfiguration & configuration) = 0;
```
在调用 [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter) 中的其他方法前,必须先调用该方法初始化 [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)。
### 参数 [#参数-9]
用于初始化 [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter) 的配置。详见 [MusicContentCenterConfiguration](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musiccontentcenterconfiguration)。
### 返回值 [#返回值-15]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-15]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## isPreloaded [#ispreloaded]
检查指定音乐资源是否已预加载。
```cpp
virtual int isPreloaded(int64_t songCode) = 0;
```
该方法为同步调用。若需预加载新的音乐资源,请调用 `preload`。
### 参数 [#参数-10]
音乐资源的 ID,用于标识一个音乐项。
### 返回值 [#返回值-16]
- 0:方法调用成功,音乐资源已预加载。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。详见错误码。
### 所属接口类 [#所属接口类-16]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## open [#open]
通过歌曲编码打开音乐资源。
```cpp
virtual int open(int64_t songCode, int64_t startPos = 0) = 0;
```
在调用该方法前,请确保要播放的音乐资源已加载。你可以调用 [isPreloaded](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_ispreloaded) 方法检查资源是否已预加载,或监听 [onPreLoadEvent](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 回调。
调用该方法后,SDK 会触发 [onPlayerSourceStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) 回调。当你收到 `PLAYER_STATE_OPEN_COMPLETED` 播放状态后,可以调用 [play](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-control#api_imediaplayer_play) 方法播放媒体文件。
:::note
注: 如果要打开的音乐资源受数字版权管理(DRM)保护,必须使用该方法打开。对于非 DRM 保护的资源,你可以选择使用该方法或 [open](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusicplayer_open_imusicplayer) 方法打开。
:::
### 相关回调 [#相关回调-3]
成功调用该方法后,SDK 会触发 [onPlayerSourceStateChanged](/zh-CN/api-reference/rtc/cpp-all-platforms/play/mediaplayer/mediaplayer-observer#callback_imediaplayersourceobserver_onplayersourcestatechanged) 回调报告播放状态。
### 参数 [#参数-11]
音乐资源的歌曲编码,用于标识音乐。
开始播放的位置,单位为毫秒。默认值为 0。
### 返回值 [#返回值-17]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-17]
- [IMusicPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusicplayer)
## preload [1/2] [#preload-12]
预加载音乐资源。
```cpp
virtual int preload(int64_t songCode, const char* jsonOption) __deprecated = 0;
```
:::error[废弃]
该方法已废弃,请改用 [preload [2/2]](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_preload2) 方法。
:::
你可以调用该方法预加载想要播放的音乐资源。成功调用该方法后,SDK 会触发 [onPreLoadEvent](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 回调报告预加载事件。在调用该方法之前,你需要先调用 `getMusicCollectionWithMusicChartId` 或 [searchMusic](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_searchmusic) 获取目标音乐资源,并从 [onMusicCollectionResult](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调中获取歌曲编号 `songCode`。
:::note
注: 在销毁 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象前,请确保已收到 [onPreLoadEvent](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 回调后再调用 [release](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_release_imusiccontentcenter) 方法。
:::
### 参数 [#参数-12]
用于标识音乐资源的歌曲编号。
扩展的 JSON 字段。声网会根据你在 `sceneType` 字段中传入的应用场景计费,不同场景的计费标准不同:
- 1:直播场景:在线 K 歌房和背景音乐播放。
- 2:直播场景:背景音乐播放。
- 3:(默认)声动语聊场景:在线 K 歌房。
- 4:声动语聊场景:背景音乐播放。
- 5:VR 场景:在线 K 歌房和背景音乐播放。
如果你需要切换到其他场景,请再次调用该方法并在该字段中传入新的 `sceneType` 值。示例:`{"sceneType":1}`。
### 返回值 [#返回值-18]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-18]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## preload [2/2] [#preload-22]
预加载音乐资源。
```cpp
virtual int preload(agora::util::AString& requestId, int64_t songCode) = 0;
```
调用该方法可以预加载想要播放的音乐资源。调用成功后,SDK 会触发 [onPreLoadEvent](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 回调报告预加载事件。在调用该方法之前,需要先调用 [getMusicCollectionByMusicChartId](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_getmusiccollectionbymusicchartid) 或 [searchMusic](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_searchmusic) 获取目标音乐资源,并从 [onMusicCollectionResult](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调中获取歌曲编码(`songCode`)。
:::note
注: 在销毁 [IRtcEngine](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_irtcengine) 对象前,请确保已收到 [onPreLoadEvent](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onpreloadevent_imusiccontentcentereventhandler) 回调后再调用 [release](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_release_imusiccontentcenter) 方法。
:::
### 参数 [#参数-13]
输出参数,请求 ID,用于唯一标识此次请求。
音乐资源的歌曲编码,用于标识音乐。
### 返回值 [#返回值-19]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-19]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## registerEventHandler [#registereventhandler]
注册 `MusicContentCenter` 的事件处理器。
```cpp
virtual int registerEventHandler(IMusicContentCenterEventHandler* eventHandler) = 0;
```
### 参数 [#参数-14]
要注册的事件处理器。详见 [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcentereventhandler)。
### 返回值 [#返回值-20]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-20]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## release [#release]
释放 `MusicContentCenter` 使用的所有资源。
```cpp
virtual void release() = 0;
```
该方法必须在调用 [release](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_release_imusiccontentcenter) 之前调用。
### 所属接口类 [#所属接口类-21]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## removeCache [#removecache]
删除已缓存的音乐资源。
```cpp
virtual int removeCache(int64_t songCode) = 0;
```
你可以调用此方法删除指定的已缓存音乐资源。若需删除多个资源,请多次调用此方法。
:::note
注: 注意:此方法不会删除当前正在播放的已缓存音乐资源。
:::
### 参数 [#参数-15]
要删除的音乐资源的 ID。
### 返回值 [#返回值-21]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-22]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## renewToken [#renewtoken]
更新 Token。
```cpp
virtual int renewToken(const char* token) = 0;
```
当用于鉴权的 Token 即将过期或已经过期时,你可以调用该方法传入新生成的 Token。
### 参数 [#参数-16]
新的 Token。
### 返回值 [#返回值-22]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-23]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/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;
```
### 相关回调 [#相关回调-4]
成功调用该方法后,SDK 会触发 [onMusicCollectionResult](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调报告检索到的音乐资源列表。
### 参数 [#参数-17]
请求 ID,用于标识该请求的唯一标识符。
搜索关键词,支持按歌曲名称或歌手名称搜索。
要获取的音乐资源列表的页码。
每页返回的最大音乐资源数量,最大值为 50。
扩展 JSON 字段,默认为 NULL。你可以使用该字段筛选所需的音乐资源。目前支持以下筛选项:
- `pitchType`:是否支持评分:
- `1`:可评分音乐。
- `2`:不可评分音乐。
- `needHighPart`:是否需要合唱片段:
- true:需要合唱片段。
- false:不需要合唱片段。
示例:`{"pitchType":1}`,`{"needHighPart":true}`。
### 返回值 [#返回值-23]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-24]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## setPlayMode [#setplaymode]
设置音乐资源的播放模式。
```cpp
virtual int setPlayMode(MusicPlayMode mode) = 0;
```
你可以调用该方法启用原唱、伴奏或导唱模式。如果不调用该方法,默认播放伴奏;若音乐资源不包含伴奏,则播放原唱。
:::note
注: 你可以通过 [onMusicCollectionResult](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#callback_imusiccontentcentereventhandler_onmusiccollectionresult) 回调获取音乐资源的详细信息,并从 `result` 参数中判断该音乐资源支持的播放模式。
:::
### 适用场景 [#适用场景]
在在线 K 歌或才艺展示等娱乐场景中,如果你需要播放由声网内容中心提供的版权音乐,可以调用该方法设置播放模式。
### 调用时机 [#调用时机-1]
该方法必须在调用 [createMusicPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_createmusicplayer) 之后调用。
### 参数 [#参数-18]
播放模式。详见 [MusicPlayMode](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-musicplaymode)。
### 返回值 [#返回值-24]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
- -2:参数无效。请重新设置参数。
### 所属接口类 [#所属接口类-25]
- [IMusicPlayer](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusicplayer)
## unregisterEventHandler [#unregistereventhandler]
取消注册 `MusicContentCenter` 的事件回调。
```cpp
virtual int unregisterEventHandler() = 0;
```
### 返回值 [#返回值-25]
- 0:方法调用成功。
- < 0:方法调用失败。详见[错误码](/zh-CN/api-reference/rtc/error-code)了解详情和解决建议。
### 所属接口类 [#所属接口类-26]
- [IMusicContentCenter](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcenter)
## onLyricResult [#onlyricresult]
获取歌词下载链接的回调。
```cpp
virtual void onLyricResult(const char* requestId, int64_t songCode, const char* lyricUrl, MusicContentCenterStateReason reason) = 0;
```
调用 [getLyric](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_getlyric) 获取某首歌曲的歌词下载链接后,SDK 会触发该回调。
### 参数 [#参数-19]
请求 ID,用于标识此次请求的唯一标识符。
音乐资源的 ID,用于标识歌曲。
歌词的下载链接。
请求状态码,详见 [MusicContentCenterStateReason](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-musiccontentcenterstatereason)。
### 所属接口类 [#所属接口类-27]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcentereventhandler)
## onMusicChartsResult [#onmusicchartsresult]
获取音乐排行榜结果的回调。
```cpp
virtual void onMusicChartsResult(const char* requestId, agora_refptr result, MusicContentCenterStateReason reason) = 0;
```
调用 [getMusicCharts](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_getmusiccharts) 后,SDK 会触发该回调。
### 参数 [#参数-20]
请求 ID,用于标识本次请求的唯一性。
当前可播放的音乐排行榜列表。详见 [MusicChartCollection](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_musicchartcollection)。
请求的状态码。详见 [MusicContentCenterStateReason](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-musiccontentcenterstatereason)。
### 所属接口类 [#所属接口类-28]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcentereventhandler)
## onMusicCollectionResult [#onmusiccollectionresult]
获取音乐资源列表的回调。
```cpp
virtual void onMusicCollectionResult(const char* requestId, agora_refptr result, MusicContentCenterStateReason reason) = 0;
```
调用 [getMusicCollectionByMusicChartId](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_getmusiccollectionbymusicchartid) 获取某个榜单的音乐资源列表,或调用 [searchMusic](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_searchmusic) 搜索音乐资源时,SDK 会触发该回调,返回音乐资源列表的详细信息。
### 触发时机 [#触发时机]
调用 [getMusicCollectionByMusicChartId](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_getmusiccollectionbymusicchartid) 或 [searchMusic](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_searchmusic) 后触发。
### 参数 [#参数-21]
请求 ID,用于标识此次请求的唯一标识符。
音乐资源列表的详细信息。详见 [MusicCollection](/zh-CN/api-reference/rtc/cpp-all-platforms/class-musiccollection)。
请求状态码。详见 [MusicContentCenterStateReason](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-musiccontentcenterstatereason)。
### 所属接口类 [#所属接口类-29]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/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;
```
调用 `preload` 预加载音乐资源后,SDK 会触发该回调。
### 参数 [#参数-22]
请求 ID,用于标识该次请求的唯一标识符。
音乐资源的 ID,用于标识某个音乐项。
音乐资源当前的加载进度,范围为 [0, 100]。
歌词的下载地址。
音乐资源当前的加载状态,详见 [PreloadState](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-preloadstate)。
来自音乐内容中心的请求状态码,详见 [MusicContentCenterStateReason](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-musiccontentcenterstatereason)。
### 所属接口类 [#所属接口类-30]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcentereventhandler)
## onSongSimpleInfoResult [#onsongsimpleinforesult]
获取音乐资源详细信息的回调。
```cpp
virtual void onSongSimpleInfoResult(const char* requestId, int64_t songCode, const char* simpleInfo, MusicContentCenterStateReason reason) = 0;
```
调用 [getSongSimpleInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_getsongsimpleinfo) 后,SDK 会触发该回调。
### 触发时机 [#触发时机-1]
调用 [getSongSimpleInfo](/zh-CN/api-reference/rtc/cpp-all-platforms/play/drm#api_imusiccontentcenter_getsongsimpleinfo) 后触发。
### 参数 [#参数-23]
请求 ID,用于标识此次请求的唯一标识符。
音乐资源的 ID,用于标识该音乐。
音乐资源的相关信息,包括以下内容:
- 副歌片段的起止时间(毫秒)。
- 副歌歌词的下载链接。
- 副歌片段的时长(毫秒)。
- 歌曲名称。
- 艺术家名称。
请求状态码,详见 [MusicContentCenterStateReason](/zh-CN/api-reference/rtc/cpp-all-platforms/enum-musiccontentcenterstatereason)。
### 所属接口类 [#所属接口类-31]
- [IMusicContentCenterEventHandler](/zh-CN/api-reference/rtc/cpp-all-platforms/rtc-interface-class#class_imusiccontentcentereventhandler)