版权音乐

createMusicPlayer

创建一个音乐播放器。

C++

virtual agora_refptr<IMusicPlayer> createMusicPlayer() = 0;

如果你需要播放来自声网 Music Content Center 的音乐资源，必须先调用 createMusicPlayer 创建一个音乐播放器。

返回值

• 方法调用成功，返回一个 IMusicPlayer 对象，详见 IMusicPlayer。
• 方法调用失败，返回 NULL。

所属接口类

• IMusicContentCenter

destroyMusicPlayer

销毁音乐播放器对象。

C++

virtual int destroyMusicPlayer(agora_refptr<IMusicPlayer> music_player) = 0;

当你不再需要使用音乐播放器时，可以调用此方法销毁该对象。如果销毁后需要再次使用音乐播放器，请调用 createMusicPlayer 重新创建。

调用时机

该方法可以在加入频道前或加入频道后调用，但必须在调用 release 方法之前调用。

参数

music_player

音乐播放器对象。详见 IMusicPlayer。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicContentCenter

get

获取指定音乐榜单的详细信息。

C++

virtual MusicChartInfo* get(int index) = 0;

参数

index

MusicChartInfo 数组中的索引。

返回值

• 方法调用成功，返回 MusicChartInfo 实例，详见 MusicChartInfo。
• 方法调用失败，返回 NULL。

所属接口类

• MusicChartCollection

getCaches

获取已缓存的音乐资源信息。

C++

virtual int getCaches(MusicCacheInfo *cacheInfo, int32_t* cacheInfoSize) = 0;

调用该方法前，需要预先分配内存用于存储已缓存音乐资源的信息。如果希望设置可缓存的音乐资源数量，可以通过 initialize 中的 configuration 参数进行配置。当不再需要这些缓存资源时，应及时释放内存以避免内存泄漏。

参数

cacheInfo

输出参数，用于存储已缓存音乐资源信息的内存缓冲区指针。详见 MusicCacheInfo。

cacheInfoSize

输入和输出参数，表示 MusicCacheInfo 数组的大小。

• 输入值：分配的 MusicCacheInfo 结构体数量。
• 输出值：方法执行后返回的 MusicCacheInfo 结构体数量。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicContentCenter

getCount [1/2]

获取当前请求中的音乐排行榜数量。

C++

virtual int getCount() = 0;

返回值

方法调用成功，返回当前请求中的音乐排行榜数量。

所属接口类

• MusicChartCollection

getCount [2/2]

获取当前请求中的音乐项数量。

C++

virtual int getCount() = 0;

返回值

方法调用成功，返回当前请求中的音乐项数量。

所属接口类

• MusicCollection

getInternalSongCode

创建音乐资源副歌片段的内部歌曲编码。

C++

virtual int getInternalSongCode(int64_t songCode, const char* jsonOption, int64_t& internalSongCode) = 0;

在播放音乐资源的副歌片段前，需调用该方法，结合参数 jsonOption 和音乐资源的 songCode 创建副歌片段的内部歌曲编码。该编码作为资源的唯一标识。获取该编码后，在调用打开、预加载或移除资源的方法时，将其作为 songCode 参数传入。

参数

songCode

音乐资源的歌曲编码，用于标识资源。你可以通过调用 getMusicCollectionByMusicChartId 或 searchMusic 获取，并从这些方法触发的 onMusicCollectionResult 回调中获取该编码。

jsonOption

扩展 JSON 字段，默认为 NULL。目前支持以下字段：

• sceneType：场景类型。1：直播场景，在线 K 歌房和背景音乐播放；2：直播场景，背景音乐播放；3：（默认）声动语聊场景，在线 K 歌房；4：声动语聊场景，背景音乐播放；5：VR 场景，在线 K 歌房和背景音乐播放。示例代码 {"sceneType":1}。
• highPart：副歌片段的索引，从 onMusicCollectionResult 回调中获取，索引从 0 开始。示例代码 {"format": {"highpart": 0}}。

internalSongCode

输出参数，音乐资源的内部歌曲编码。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。详见错误码及其解决建议。

所属接口类

• IMusicContentCenter

getLyric

获取音乐资源歌词的下载链接。

C++

virtual int getLyric(agora::util::AString& requestId, int64_t songCode, int32_t lyricType = 0) = 0;

相关回调

调用该方法后，SDK 会触发 onLyricResult 回调报告歌词下载链接。

参数

requestId

请求 ID，用于唯一标识该请求。

songCode

音乐资源的 ID，用于标识音乐。

lyricType

歌词类型：

• 0：XML 格式。
• 1：LRC 格式。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicContentCenter

getMusic

获取当前页面中指定音乐资源的详细信息。

C++

virtual Music* getMusic(int32_t index) = 0;

参数

index

Music 数组中的索引。

返回值

• 方法调用成功，返回 Music 实例，详见 Music。
• 方法调用失败，返回 NULL。

所属接口类

• MusicCollection

getMusicCharts

获取所有音乐排行榜。

C++

virtual int getMusicCharts(agora::util::AString& requestId) = 0;

相关回调

成功调用该方法后，SDK 会触发 onMusicChartsResult 回调，报告音乐排行榜的详细信息。

参数

requestId

用于标识此次请求的唯一标识符。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicContentCenter

getMusicCollectionByMusicChartId

获取指定音乐榜单 ID 的音乐资源列表。

C++

virtual int getMusicCollectionByMusicChartId(agora::util::AString& requestId, int32_t musicChartId, int32_t page, int32_t pageSize, const char* jsonOption = nullptr) = 0;

调用该方法后，SDK 会触发 onMusicCollectionResult 回调，报告该榜单中的音乐资源详情。

参数

requestId

请求 ID，用于标识该请求的唯一标识符。

musicChartId

音乐榜单的 ID。你可以通过 onMusicChartsResult 回调获取该 ID，或通过 RESTful API 获取完整音乐库列表或增量音乐列表。

page

当前页码，从 1 开始。

pageSize

每页返回的音乐资源数量，最大值为 50。

jsonOption

扩展 JSON 字段，默认为 NULL。你可以使用该字段筛选所需的音乐资源。目前支持以下筛选项：

• pitchType：是否支持评分。
  • 1：可评分音乐。
  • 2：不可评分音乐。
• needHighPart：是否需要合唱片段。
  • true：需要合唱片段。
  • false：不需要合唱片段。

示例：

• { "pitchType": 1 }
• { "needHighPart": true }

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。请参见错误码文档获取详细信息和解决方案。

所属接口类

• IMusicContentCenter

getPage

获取音乐资源列表当前的页码。

C++

virtual int getPage() = 0;

返回值

方法调用成功，返回当前页码。

所属接口类

• MusicCollection

getPageSize

获取 SDK 实际返回的音乐资源数量。

C++

virtual int getPageSize() = 0;

返回值

方法调用成功，返回 SDK 实际返回的音乐资源数量。

所属接口类

• MusicCollection

getSongSimpleInfo

获取指定音乐资源的详细信息。

C++

virtual int getSongSimpleInfo(agora::util::AString& requestId, int64_t songCode) = 0;

调用该方法前，你需要先获取目标音乐资源的歌曲编号。你可以通过调用 getMusicCollectionByMusicChartId 或 searchMusic 方法，并从其触发的 onMusicCollectionResult 回调中获取歌曲编号。调用该方法后，SDK 会触发 onSongSimpleInfoResult 回调，返回该音乐资源的详细信息。

相关回调

成功调用该方法后，SDK 会触发 onSongSimpleInfoResult 回调，返回音乐资源的详细信息。

参数

requestId

请求 ID，用于唯一标识该请求。

songCode

音乐资源的歌曲编号，用于标识音乐。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicContentCenter

getTotal

获取音乐资源列表中的总数。

C++

virtual int getTotal() = 0;

返回值

方法调用成功，返回音乐资源的总数。

所属接口类

• MusicCollection

initialize

初始化 IMusicContentCenter。

C++

virtual int initialize(const MusicContentCenterConfiguration & configuration) = 0;

在调用 IMusicContentCenter 中的其他方法前，必须先调用该方法初始化 IMusicContentCenter。

参数

configuration

用于初始化 IMusicContentCenter 的配置。详见 MusicContentCenterConfiguration。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicContentCenter

isPreloaded

检查指定音乐资源是否已预加载。

C++

virtual int isPreloaded(int64_t songCode) = 0;

该方法为同步调用。若需预加载新的音乐资源，请调用 preload。

参数

songCode

音乐资源的 ID，用于标识一个音乐项。

返回值

• 0：方法调用成功，音乐资源已预加载。
• < 0：方法调用失败。详见错误码了解详情和解决建议。详见错误码。

所属接口类

• IMusicContentCenter

open

通过歌曲编码打开音乐资源。

C++

virtual int open(int64_t songCode, int64_t startPos = 0) = 0;

在调用该方法前，请确保要播放的音乐资源已加载。你可以调用 isPreloaded 方法检查资源是否已预加载，或监听 onPreLoadEvent 回调。 调用该方法后，SDK 会触发 onPlayerSourceStateChanged 回调。当你收到 PLAYER_STATE_OPEN_COMPLETED 播放状态后，可以调用 play 方法播放媒体文件。

信息

如果要打开的音乐资源受数字版权管理（DRM）保护，必须使用该方法打开。对于非 DRM 保护的资源，你可以选择使用该方法或 open 方法打开。

相关回调

成功调用该方法后，SDK 会触发 onPlayerSourceStateChanged 回调报告播放状态。

参数

songCode

音乐资源的歌曲编码，用于标识音乐。

startPos

开始播放的位置，单位为毫秒。默认值为 0。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicPlayer

preload [1/2]

预加载音乐资源。

C++

virtual int preload(int64_t songCode, const char* jsonOption) __deprecated = 0;

废弃

该方法已废弃，请改用 preload [2/2] 方法。

你可以调用该方法预加载想要播放的音乐资源。成功调用该方法后，SDK 会触发 onPreLoadEvent 回调报告预加载事件。在调用该方法之前，你需要先调用 getMusicCollectionWithMusicChartId 或 searchMusic 获取目标音乐资源，并从 onMusicCollectionResult 回调中获取歌曲编号 songCode。

信息

在销毁 IRtcEngine 对象前，请确保已收到 onPreLoadEvent 回调后再调用 release 方法。

参数

songCode

用于标识音乐资源的歌曲编号。

jsonOption

扩展的 JSON 字段。声网会根据你在 sceneType 字段中传入的应用场景计费，不同场景的计费标准不同：

• 1：直播场景：在线 K 歌房和背景音乐播放。
• 2：直播场景：背景音乐播放。
• 3：（默认）声动语聊场景：在线 K 歌房。
• 4：声动语聊场景：背景音乐播放。
• 5：VR 场景：在线 K 歌房和背景音乐播放。

如果你需要切换到其他场景，请再次调用该方法并在该字段中传入新的 sceneType 值。示例：{"sceneType":1}。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicContentCenter

preload [2/2]

预加载音乐资源。

C++

virtual int preload(agora::util::AString& requestId, int64_t songCode) = 0;

调用该方法可以预加载想要播放的音乐资源。调用成功后，SDK 会触发 onPreLoadEvent 回调报告预加载事件。在调用该方法之前，需要先调用 getMusicCollectionByMusicChartId 或 searchMusic 获取目标音乐资源，并从 onMusicCollectionResult 回调中获取歌曲编码（songCode）。

信息

在销毁 IRtcEngine 对象前，请确保已收到 onPreLoadEvent 回调后再调用 release 方法。

参数

requestId

输出参数，请求 ID，用于唯一标识此次请求。

songCode

音乐资源的歌曲编码，用于标识音乐。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicContentCenter

registerEventHandler

注册 MusicContentCenter 的事件处理器。

C++

virtual int registerEventHandler(IMusicContentCenterEventHandler* eventHandler) = 0;

参数

eventHandler

要注册的事件处理器。详见 IMusicContentCenterEventHandler。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicContentCenter

release

释放 MusicContentCenter 使用的所有资源。

C++

virtual void release() = 0;

该方法必须在调用 release 之前调用。

所属接口类

• IMusicContentCenter

removeCache

删除已缓存的音乐资源。

C++

virtual int removeCache(int64_t songCode) = 0;

你可以调用此方法删除指定的已缓存音乐资源。若需删除多个资源，请多次调用此方法。

信息

注意：此方法不会删除当前正在播放的已缓存音乐资源。

参数

songCode

要删除的音乐资源的 ID。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicContentCenter

renewToken

更新 Token。

C++

virtual int renewToken(const char* token) = 0;

当用于鉴权的 Token 即将过期或已经过期时，你可以调用该方法传入新生成的 Token。

参数

token

新的 Token。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicContentCenter

searchMusic

搜索音乐资源。

C++

virtual int searchMusic(agora::util::AString& requestId, const char* keyWord, int32_t page, int32_t pageSize, const char* jsonOption = nullptr) = 0;

相关回调

成功调用该方法后，SDK 会触发 onMusicCollectionResult 回调报告检索到的音乐资源列表。

参数

requestId

请求 ID，用于标识该请求的唯一标识符。

keyWord

搜索关键词，支持按歌曲名称或歌手名称搜索。

page

要获取的音乐资源列表的页码。

pageSize

每页返回的最大音乐资源数量，最大值为 50。

jsonOption

扩展 JSON 字段，默认为 NULL。你可以使用该字段筛选所需的音乐资源。目前支持以下筛选项：

• pitchType：是否支持评分：
  • 1：可评分音乐。
  • 2：不可评分音乐。
• needHighPart：是否需要合唱片段：
  • true：需要合唱片段。
  • false：不需要合唱片段。

示例：{"pitchType":1}，{"needHighPart":true}。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicContentCenter

setPlayMode

设置音乐资源的播放模式。

C++

virtual int setPlayMode(MusicPlayMode mode) = 0;

你可以调用该方法启用原唱、伴奏或导唱模式。如果不调用该方法，默认播放伴奏；若音乐资源不包含伴奏，则播放原唱。

信息

你可以通过 onMusicCollectionResult 回调获取音乐资源的详细信息，并从 result 参数中判断该音乐资源支持的播放模式。

适用场景

在在线 K 歌或才艺展示等娱乐场景中，如果你需要播放由声网内容中心提供的版权音乐，可以调用该方法设置播放模式。

调用时机

该方法必须在调用 createMusicPlayer 之后调用。

参数

mode

播放模式。详见 MusicPlayMode。

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。
  • -2：参数无效。请重新设置参数。

所属接口类

• IMusicPlayer

unregisterEventHandler

取消注册 MusicContentCenter 的事件回调。

C++

virtual int unregisterEventHandler() = 0;

返回值

• 0：方法调用成功。
• < 0：方法调用失败。详见错误码了解详情和解决建议。

所属接口类

• IMusicContentCenter

onLyricResult

获取歌词下载链接的回调。

C++

virtual void onLyricResult(const char* requestId, int64_t songCode, const char* lyricUrl, MusicContentCenterStateReason reason) = 0;

调用 getLyric 获取某首歌曲的歌词下载链接后，SDK 会触发该回调。

参数

requestId

请求 ID，用于标识此次请求的唯一标识符。

songCode

音乐资源的 ID，用于标识歌曲。

lyricUrl

歌词的下载链接。

reason

请求状态码，详见 MusicContentCenterStateReason。

所属接口类

• IMusicContentCenterEventHandler

onMusicChartsResult

获取音乐排行榜结果的回调。

C++

virtual void onMusicChartsResult(const char* requestId, agora_refptr<MusicChartCollection> result, MusicContentCenterStateReason reason) = 0;

调用 getMusicCharts 后，SDK 会触发该回调。

参数

requestId

请求 ID，用于标识本次请求的唯一性。

result

当前可播放的音乐排行榜列表。详见 MusicChartCollection。

reason

请求的状态码。详见 MusicContentCenterStateReason。

所属接口类

• IMusicContentCenterEventHandler

onMusicCollectionResult

获取音乐资源列表的回调。

C++

virtual void onMusicCollectionResult(const char* requestId, agora_refptr<MusicCollection> result, MusicContentCenterStateReason reason) = 0;

调用 getMusicCollectionByMusicChartId 获取某个榜单的音乐资源列表，或调用 searchMusic 搜索音乐资源时，SDK 会触发该回调，返回音乐资源列表的详细信息。

触发时机

调用 getMusicCollectionByMusicChartId 或 searchMusic 后触发。

参数

requestId

请求 ID，用于标识此次请求的唯一标识符。

result

音乐资源列表的详细信息。详见 MusicCollection。

reason

请求状态码。详见 MusicContentCenterStateReason。

所属接口类

• IMusicContentCenterEventHandler

onPreLoadEvent

预加载音乐资源相关事件的回调。

C++

virtual void onPreLoadEvent(const char* requestId, int64_t songCode, int percent, const char* lyricUrl, PreloadState state, MusicContentCenterStateReason reason) = 0;

调用 preload 预加载音乐资源后，SDK 会触发该回调。

参数

requestId

请求 ID，用于标识该次请求的唯一标识符。

songCode

音乐资源的 ID，用于标识某个音乐项。

percent

音乐资源当前的加载进度，范围为 [0, 100]。

lyricUrl

歌词的下载地址。

state

音乐资源当前的加载状态，详见 PreloadState。

reason

来自音乐内容中心的请求状态码，详见 MusicContentCenterStateReason。

所属接口类

• IMusicContentCenterEventHandler

onSongSimpleInfoResult

获取音乐资源详细信息的回调。

C++

virtual void onSongSimpleInfoResult(const char* requestId, int64_t songCode, const char* simpleInfo, MusicContentCenterStateReason reason) = 0;

调用 getSongSimpleInfo 后，SDK 会触发该回调。

触发时机

调用 getSongSimpleInfo 后触发。

参数

requestId

请求 ID，用于标识此次请求的唯一标识符。

songCode

音乐资源的 ID，用于标识该音乐。

simpleInfo

音乐资源的相关信息，包括以下内容：

• 副歌片段的起止时间（毫秒）。
• 副歌歌词的下载链接。
• 副歌片段的时长（毫秒）。
• 歌曲名称。
• 艺术家名称。

reason

请求状态码，详见 MusicContentCenterStateReason。

所属接口类

• IMusicContentCenterEventHandler