版权音乐
- Unreal C++
更新时间不可用
createMusicPlayer
创建音乐播放器。
virtual agora_refptr<IMusicPlayer> createMusicPlayer() = 0;详情
如果你需要播放音乐内容中心的音乐资源，你需要先调用该方法来创建一个音乐播放器。
返回值
- 方法调用成功：返回 IMusicPlayer 对象。
- 方法调用失败：返回空指针。
所属接口类
destroyMusicPlayer
销毁音乐播放器对象。
virtual int destroyMusicPlayer(agora_refptr<IMusicPlayer> music_player) = 0;当你不再需要使用音乐播放器时，你可以调用该方法来销毁音乐播放器对象。销毁之后如果需要重新使用音乐播放器，需要调用 createMusicPlayer 重新创建一个音乐播放器对象。
调用时机
该方法在加入频道前后均可调用，但请确保在 IRtcEngine 的 Release 方法前调用。
调用限制
无。
参数
| 参数名 | 描述 |
|---|---|
music_player | IMusicPlayer 对象。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
getCaches
获取已缓存的音乐资源信息。
virtual int getCaches(MusicCacheInfo *cacheInfo, int32_t* cacheInfoSize) = 0;详情
调用该方法前，你需要预先分配一定大小的内存空间用来存储缓存音乐资源的信息。如果你需要设置可缓存的音乐资源数量，可通过 initialize 的 configuration 来设置。
当你不再需要使用已缓存的音乐资源时，你需要及时释放内存以防止内存泄漏。
参数
| 参数名 | 描述 |
|---|---|
cacheInfo | |
cacheInfoSize |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
getCount [2/2]
获取本次请求的音乐数量。
virtual int getCount() = 0;详情
返回值
本次请求的音乐数量。
get
获取音乐榜单的详细信息。
virtual MusicChartInfo* get(int index) = 0;详情
参数
| 参数名 | 描述 |
|---|---|
index | MusicChartInfo 数组的索引。 |
返回值
MusicChartInfo，包含音乐榜单的详细信息。
getInternalSongCode
创建音乐资源的副歌片段编号。
virtual int getInternalSongCode(int64_t songCode, const char* jsonOption, int64_t& internalSongCode) = 0;适用场景
当你需要播放某一音乐资源的副歌片段前，你需要调用此方法，通过 jsonOption 参数和该音乐资源的 songCode 来为该音乐资源的副歌片段创建一个编号，作为该资源的唯一标识。当你获取到该片段的编号后，在你调用相应方法打开、预加载、移除该资源时，将该内部歌曲编号传入 songCode 参数。
参数
| 参数名 | 描述 | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
songCode | 音乐资源编号，用于标识音乐资源。你可以通过调用 getMusicCollectionWithMusicChartId 或 searchMusic 方法来获取音乐资源，并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号（songCode）。 | |||||||||
jsonOption | 扩展 JSON 字段，默认为 NULL。目前支持传入下列值：
| |||||||||
internalSongCode |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
getLyric
获取音乐资源的歌词下载地址。
virtual int getLyric(agora::util::AString& requestId, int64_t songCode, int32_t LyricType = 0) = 0;详情
成功调用该方法后，SDK 会触发 onLyricResult 回调报告歌词的下载地址。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
getMusic
获取当前页面列表中音乐资源的详细信息。
virtual Music* getMusic(int32_t index) = 0;详情
参数
| 参数名 | 描述 |
|---|---|
index | Music 数组的索引。 |
返回值
一个 Music 实例。
getMusicCharts
获取全部音乐榜单。
virtual int getMusicCharts(agora::util::AString& requestId) = 0;详情
当你调用该方法后，SDK 会触发 onMusicChartsResult 回调报告音乐榜单的详细信息。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
getMusicCollectionWithMusicChartId
通过音乐榜单的 ID 获取指定榜单的音乐资源列表。
virtual int getMusicCollectionByMusicChartId(agora::util::AString& requestId, int32_t musicChartId, int32_t page, int32_t pageSize, const char* jsonOption = nullptr) = 0;详情
成功调用该方法后，SDK 会触发 onMusicCollectionResult 回调报告榜单中音乐资源列表的详细信息。
参数
| 参数名 | 描述 |
|---|---|
requestId | |
musicChartId | 音乐榜单的 ID，可以通过 onMusicChartsResult 回调获取。你也可以通过 RESTful API 来获取曲库所有歌曲列表或获取增量歌曲列表。 |
page | |
pageSize | |
jsonOption |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
getPage
获取音乐资源列表当前页的页码。
virtual int getPage() = 0;详情
返回值
当前页的页码。
getPageSize
获取 SDK 实际返回的音乐资源数量。
virtual int getPageSize() = 0;详情
返回值
SDK 实际返回的音乐资源数量。
getTotal
获取列表内音乐资源的总数量。
virtual int getTotal() = 0;详情
返回值
列表内音乐资源的总数量。
getSongSimpleInfo
获取某一音乐资源的详细信息。
virtual int getSongSimpleInfo(agora::util::AString& requestId, int64_t songCode) = 0;详情
在调用该方法前，你需要先获取到对应的音乐资源的编号。你可以通过调用 getMusicCollectionWithMusicChartId 或 searchMusic 方法来获取音乐资源，并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号（songCode）。
当你调用该方法后，SDK 会触发 onSongSimpleInfoResult 回调报告音乐资源的详细信息。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
initialize
初始化 IMusicContentCenter。
virtual int initialize(const MusicContentCenterConfiguration & configuration) = 0;详情
在调用 IMusicContentCenter 类下的其他方法前，你需要先调用该方法初始化 IMusicContentCenter。
参数
| 参数名 | 描述 |
|---|---|
configuration | IMusicContentCenter 的设置，详见 MusicContentCenterConfiguration。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
isPreloaded
检测音乐资源是否已被预加载。
virtual int isPreloaded(int64_t songCode) = 0;详情
该方法为同步调用。如需预加载新的音乐资源，可调用 preload [2/2]。
参数
返回值
- 0: 方法调用成功，该音乐资源已被预加载。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
preload [1/2]
预加载音乐资源。
virtual int preload(int64_t songCode, const char* jsonOption = nullptr) = 0;详情
你可以调用该方法预先加载需要播放的音乐资源。成功调用该方法后，SDK 会触发 onPreLoadEvent 回调报告预加载音乐资源的事件。
在调用该方法来预加载音乐资源之前，你需要调用 getMusicCollectionWithMusicChartId 或 searchMusic 方法来获取你需要播放的音乐资源，并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号（songCode）。
注意： 如需销毁 IRtcEngine 对象，请在收到 onPreLoadEvent 回调后，再调用 Release 方法。
参数
| 参数名 | 描述 |
|---|---|
songCode | |
jsonOption | 扩展 JSON 字段。 声网会根据你在场景字段（sceneType）传入的应用场景进行收费。不同的应用场景对应不同的费率，你可以参考 计费说明 查看详细的计费。
如果需要切换到不同场景，需要重新调用此方法并在该字段中传入 sceneType 的值。 示例： |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
preload [2/2]
预加载音乐资源。
virtual int preload(agora::util::AString& requestId, int64_t songCode) = 0;详情
你可以调用该方法预先加载需要播放的音乐资源。成功调用该方法后，SDK 会触发 onPreLoadEvent 回调报告预加载音乐资源的事件。
在调用该方法来预加载音乐资源之前，你需要调用 getMusicCollectionWithMusicChartId 或 searchMusic 方法来获取你需要播放的音乐资源，并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号（songCode）。
注意： 如需销毁 IRtcEngine 对象，请在收到 onPreLoadEvent 回调后，再调用 Release 方法。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
registerEventHandler
注册音乐内容中心回调事件。
virtual int registerEventHandler(IMusicContentCenterEventHandler* eventHandler) = 0;详情
参数
| 参数名 | 描述 |
|---|---|
eventHandler | 待注册的回调事件，详见 IMusicContentCenterEventHandler。 |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
release
释放音乐内容中心所占用的所有资源。
virtual void release() = 0;详情
该方法需要在 IRtcEngine 的 Release 方法前调用。
所属接口类
removeCache
删除已缓存的音乐资源。
virtual int removeCache(int64_t songCode) = 0;详情
你可以调用该方法删除某一已缓存的音乐资源，如需删除多个音乐资源，你可以多次调用该方法。
注： 该方法不会删除正在播放中的已缓存音乐资源。
参数
返回值
- 0: 方法调用成功，音乐资源已删除。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
renewToken
更新 Token。
virtual int renewToken(const char* token) = 0;详情
当你用于鉴权的 Token 快要过期或已过期时，你可以调用该方法来传入新生成的 Token。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
searchMusic
搜索音乐资源。
virtual int searchMusic(agora::util::AString& requestId, const char* keyWord, int32_t page, int32_t pageSize, const char* jsonOption = nullptr) = 0;详情
成功调用该方法后，SDK 会触发 onMusicCollectionResult 回调报告检索到的音乐资源列表。
参数
| 参数名 | 描述 |
|---|---|
keyword | |
page | |
pageSize | |
jsonOption | |
requestId |
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
setPlayMode
设置音乐资源的播放模式。
virtual int setPlayMode(MusicPlayMode mode) = 0;你可以调用该方法来设置启用原唱、伴奏或导唱。如不调用该方法进行设置，则默认播放伴奏；如果音乐资源没有伴奏，则播放原唱。
注意： 你可以通过 onMusicCollectionResult 回调获取音乐资源的详细信息，并可通过其中的 result 参数得知需播放的版权音乐所支持的播放类型。
适用场景
在线 K 歌、秀场等娱乐场景下，如果你需要播放声网内容中心提供的版权音乐，你可以调用该方法来设置播放模式。
调用时机
该方法需要在 createMusicPlayer 之后调用。
调用限制
无。
参数
| 参数名 | 描述 |
|---|---|
mode | 播放模式，详见 MusicPlayMode。 |
返回值
-
0: 方法调用成功。
-
< 0: 方法调用失败。详见错误码了解详情和解决建议。
- -2: 参数设置错误，请重新设置参数。
所属接口类
unregisterEventHandler
取消注册音乐内容中心事件回调。
virtual int unregisterEventHandler() = 0;详情
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
所属接口类
onLyricResult
歌词下载地址回调。
virtual void onLyricResult(const char* requestId, int64_t songCode, const char* lyricUrl, MusicContentCenterStateReason reason) = 0;详情
当你调用 getLyric 获取指定歌曲的歌词下载地址后，SDK 会触发该回调。
参数
| 参数名 | 描述 |
|---|---|
requestId | |
lyricUrl | |
reason | 音乐内容中心的请求状态码，详见 MusicContentCenterStateReason。 |
所属接口类
onMusicChartsResult
获取音乐榜单回调。
virtual void onMusicChartsResult(const char* requestId, agora_refptr<MusicChartCollection> result, MusicContentCenterStateReason reason) = 0;详情
当你调用 getMusicCharts 方法获取全部音乐榜单之后，SDK 会触发该回调。
参数
| 参数名 | 描述 |
|---|---|
requestId | |
reason | 音乐内容中心的请求状态码，详见 MusicContentCenterStateReason。 |
result | 当前可播放的音乐榜单列表。详见 MusicChartInfoMusicChartCollection。 |
所属接口类
onMusicCollectionResult
获取音乐资源列表回调。
virtual void onMusicCollectionResult(const char* requestId, agora_refptr<MusicCollection> result, MusicContentCenterStateReason reason) = 0;详情
当你调用 getMusicCollectionWithMusicChartId 方法来获取指定榜单的音乐资源列表或调用 searchMusic 来搜索音乐资源时，SDK 会触发此回调报告榜单中音乐资源列表的详细信息。
参数
| 参数名 | 描述 |
|---|---|
requestId | |
reason | 音乐内容中心的请求状态码，详见 MusicContentCenterStateReason。 |
result | 音乐资源列表的详细信息。详见 MusicCollection。 |
所属接口类
onPreLoadEvent
报告预加载音乐资源的事件。
virtual void onPreLoadEvent(const char* requestId, int64_t songCode, int percent, const char* lyricUrl, PreloadState state, MusicContentCenterStateReason reason) = 0;详情
当你调用 preload [1/2] 或 preload [2/2] 方法预加载音乐资源后，SDK 会触发该回调。
参数
| 参数名 | 描述 |
|---|---|
requestId | |
songCode | |
percent | |
lyricUrl | |
state | 当前音乐资源的加载状态。详见 PreloadState。 |
reason | 音乐内容中心的请求状态码，详见 MusicContentCenterStateReason。 |
所属接口类
onSongSimpleInfoResult
音乐资源的详细信息回调。
virtual void onSongSimpleInfoResult(const char* requestId, int64_t songCode, const char* simpleInfo, MusicContentCenterStateReason reason) = 0;详情
当你调用 getSongSimpleInfo 获取某一音乐资源的详细信息后，SDK 会触发该回调。
参数
| 参数名 | 描述 |
|---|---|
requestId | |
songCode | |
simpleInfo | |
reason | 音乐内容中心的请求状态码，详见 MusicContentCenterStateReason。 |
所属接口类
open
通过音乐资源编号打开音乐资源。
virtual int open(int64_t songCode, int64_t startPos = 0) = 0;详情
注： 如果你想要打开的音乐资源受数字版权保护，则需要调用此方法打开。对于不受数字版权保护的音乐资源，你可以选择通过调用此方法或 IMediaPlayer 类下的 open 方法来打开。
在调用此方法之前，请确保需要播放的音乐资源已加载完成。你可以调用 isPreloaded 方法来检测音乐资源是否已被预加载，或通过 onPreLoadEvent 回调得知。
调用该方法后会触发 onPlayerSourceStateChanged 回调。在收到报告播放状态为 PLAYER_STATE_OPEN_COMPLETED 后，你可以调用 play 方法播放媒体文件。
参数
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。