版权音乐
createMusicPlayer
创建音乐播放器。
Future<MusicPlayer> createMusicPlayer();
如果你需要播放音乐内容中心的音乐资源，你需要先调用该方法来创建一个音乐播放器。
返回值
- 方法调用成功：返回 MusicPlayer 对象。
- 方法调用失败：返回空指针。
destroyMusicPlayer
销毁音乐播放器对象。
Future<void> destroyMusicPlayer(MusicPlayer musicPlayer);
当你不再需要使用音乐播放器时，你可以调用该方法来销毁音乐播放器对象。销毁之后如果需要重新使用音乐播放器，需要调用 createMusicPlayer 重新创建一个音乐播放器对象。
参数
- musicPlayer
- MusicPlayer 对象。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类get
获取音乐榜单的详细信息。
Future<MusicChartInfo> get(int index);
参数
- index
- MusicChartInfo 数组的索引。
返回值
MusicChartInfo，包含音乐榜单的详细信息。
所属接口类getCaches
获取已缓存的音乐资源信息。
Future<List<MusicCacheInfo>> getCaches(int cacheInfoSize);
调用该方法前，你需要预先分配一定大小的内存空间用来存储缓存音乐资源的信息。如果你需要设置可缓存的音乐资源数量，可通过 initialize 的 configuration 来设置。 当你不再需要使用已缓存的音乐资源时，你需要及时释放内存以防止内存泄漏。
参数
- cacheInfoSize
- 指定要获取的缓存音乐资源列表的长度。
返回值
- 方法调用成功时，返回 MusicCacheInfo 对象的列表。
- 方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
getCount
getCount
getInternalSongCode
创建音乐资源的副歌片段编号。
Future<int> getInternalSongCode(
{required int songCode, required String jsonOption});
适用场景
当你需要播放某一音乐资源的副歌片段前，你需要调用此方法，通过 jsonOption 参数和该音乐资源的 songCode 来为该音乐资源的副歌片段创建一个编号，作为该资源的唯一标识。当你获取到该片段的编号后，在你调用相应方法打开、预加载、移除该资源时，将该内部歌曲编号传入 songCode 参数。
参数
- songCode
- 音乐资源编号，用于标识音乐资源。你可以通过调用 getMusicCollectionByMusicChartId 或 searchMusic 方法来获取音乐资源，并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号（
songCode）。 - jsonOption
- 扩展 JSON 字段，默认为信息声网会根据你在
sceneType传入的应用场景进行收费。不同的应用场景对应不同的费率，你可以参考 计费说明 查看详细的计费。如果需要切换到不同场景，需要重新调用此方法并传入sceneType的值。null。目前支持传入下列值：- sceneType：场景类型。1：直播场景，在线 K 歌房和背景音乐播放；2：直播场景，背景音乐播放；3：（默认）声动语聊场景，在线 K 歌房；4：声动语聊场景，背景音乐播放；5：VR 场景，在线 K 歌房和背景音乐播放。示例：
{"sceneType":1}。 - highPart：副歌片段的索引，从 onMusicCollectionResult 回调中获取，索引从 0 开始。示例：
{"format": {"highpart": 0}}。
- sceneType：场景类型。1：直播场景，在线 K 歌房和背景音乐播放；2：直播场景，背景音乐播放；3：（默认）声动语聊场景，在线 K 歌房；4：声动语聊场景，背景音乐播放；5：VR 场景，在线 K 歌房和背景音乐播放。示例：
返回值
- 方法调用成功，返回创建的音乐资源内部编号。
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
getLyric
获取音乐资源的歌词下载地址。
Future<String> getLyric({required int songCode, int lyricType = 0});
成功调用该方法后，SDK 会触发 onLyricResult 回调报告歌词的下载地址。
参数
- songCode
- 音乐资源的编号，用于标识音乐资源。
- lyricType
- 歌词类型：
- 0：xml 格式。
- 1：lrc 格式。
返回值
一个 requestId，为本次请求的唯一标识。
getMusicCharts
获取全部音乐榜单。
Future<String> getMusicCharts();
当你调用该方法后，SDK 会触发 onMusicChartsResult 回调报告音乐榜单的详细信息。
返回值
一个 requestId，为本次请求的唯一标识。
getMusicCollectionByMusicChartId
通过音乐榜单的 ID 获取指定榜单的音乐资源列表。
Future<String> getMusicCollectionByMusicChartId(
{required int musicChartId,
required int page,
required int pageSize,
String? jsonOption});
成功调用该方法后，SDK 会触发 onMusicCollectionResult 回调报告榜单中音乐资源列表的详细信息。
参数
- musicChartId
- page
- 当前页面编号，默认从 1 开始。
- pageSize
- 当前音乐资源列表的总页面数量，最大值为 50。
- jsonOption
- 扩展 JSON 字段，默认为
null。你可以通过该字段来筛选出你需要的音乐资源，目前支持筛选可打分的音乐资源及音乐资源的副歌片段：pitchType：音乐资源是否支持评分。1：可评分的音乐资源。2：不可评分的音乐资源。
needHighPart：是否需要合唱片段资源。YES：需要合唱片段资源。NO：不需要合唱片段资源。
返回值
一个 requestId，为本次请求的唯一标识。
getMusicContentCenter
getPage
getPageSize
getSongSimpleInfo
获取某一音乐资源的详细信息。
Future<String> getSongSimpleInfo(int songCode);
在调用该方法前，你需要先获取到对应的音乐资源的编号。你可以通过调用 getMusicCollectionByMusicChartId 或 searchMusic 方法来获取音乐资源，并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号（songCode）。 当你调用该方法后，SDK 会触发 onSongSimpleInfoResult 回调报告音乐资源的详细信息。
参数
- songCode
- 音乐资源的编号，用于标识音乐资源。
返回值
一个 requestId，为本次请求的唯一标识。
getTotal
initialize
初始化 MusicContentCenter。
Future<void> initialize(MusicContentCenterConfiguration configuration);
在调用 MusicContentCenter 类下的其他方法前，你需要先调用该方法初始化 MusicContentCenter。
参数
- configuration
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类isPreloaded
openWithSongCode
通过音乐资源编号打开音乐资源。
Future<void> openWithSongCode({required int songCode, int startPos = 0});
在调用此方法之前，请确保需要播放的音乐资源已加载完成。你可以调用 isPreloaded 方法来检测音乐资源是否已被预加载，或通过 onPreLoadEvent 回调得知。 调用该方法后会触发 onPlayerSourceStateChanged 回调。在收到报告播放状态为 playerStateOpenCompleted 后，你可以调用 play 方法播放媒体文件。
参数
- songCode
- 音乐资源的编号，用于标识音乐资源。
- startPos
- 设置起始播放位置（毫秒），默认值为 0。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类preload
预加载音乐资源。
Future<String> preload(int songCode);
你可以调用该方法预先加载需要播放的音乐资源。成功调用该方法后，SDK 会触发 onPreLoadEvent 回调报告预加载音乐资源的事件。 在调用该方法来预加载音乐资源之前，你需要调用 getMusicCollectionByMusicChartId 或 searchMusic 方法来获取你需要播放的音乐资源，并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号（songCode）。
参数
- songCode
- 音乐资源的编号，用于标识音乐资源。
返回值
一个 requestId，为本次请求的唯一标识。
registerEventHandler
注册音乐内容中心回调事件。
void registerEventHandler(MusicContentCenterEventHandler eventHandler);
参数
- eventHandler
- 待注册的回调事件，详见 MusicContentCenterEventHandler。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类release
释放音乐内容中心所占用的所有资源。
Future<void> release();
removeCache
删除已缓存的音乐资源。
Future<void> removeCache(int songCode);
你可以调用该方法删除某一已缓存的音乐资源，如需删除多个音乐资源，你可以多次调用该方法。
参数
- songCode
- 待删除的音乐资源的编号。
返回值
- < 0: 方法调用失败。详见错误码了解详情和解决建议。
renewToken
更新 Token。
Future<void> renewToken(String token);
当你用于鉴权的 Token 快要过期或已过期时，你可以调用该方法来传入新生成的 Token。
参数
- token
- 新的 Token。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类searchMusic
搜索音乐资源。
Future<String> searchMusic(
{required String keyWord,
required int page,
required int pageSize,
String? jsonOption});
成功调用该方法后，SDK 会触发 onMusicCollectionResult 回调报告检索到的音乐资源列表。
参数
- keyword
- 搜索关键词，支持歌曲名、歌手搜索。
- page
- 想要获取的音乐资源列表的目标页编号。
- pageSize
- 每页所展示的音乐资源的最大数量，最大值为 50。
- jsonOption
- 扩展 JSON 字段，默认为
null。你可以通过该字段来筛选出你需要的音乐资源，目前支持筛选可打分的音乐资源及音乐资源的副歌片段：pitchType：音乐资源是否支持评分。1：可评分的音乐资源。2：不可评分的音乐资源。
needHighPart：是否需要合唱片段资源。YES：需要合唱片段资源。NO：不需要合唱片段资源。
返回值
一个 requestId，为本次请求的唯一标识。
setPlayMode
设置音乐资源的播放模式。
Future<void> setPlayMode(MusicPlayMode mode);
你可以调用该方法来设置启用原唱、伴奏或导唱。如不调用该方法进行设置，则默认播放伴奏；如果音乐资源没有伴奏，则播放原唱。
result 参数得知需播放的版权音乐所支持的播放类型。适用场景
在线 K 歌、秀场等娱乐场景下，如果你需要播放声网内容中心提供的版权音乐，你可以调用该方法来设置播放模式。
调用时机
该方法需要在 createMusicPlayer 之后调用。
参数
- mode
- 播放模式，详见 MusicPlayMode。
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类unregisterEventHandler
取消注册音乐内容中心事件回调。
void unregisterEventHandler();
返回值
方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。
所属接口类onLyricResult
歌词下载地址回调。
final void Function(String requestId, int songCode, String lyricUrl,
MusicContentCenterStateReason reason)? onLyricResult;
当你调用 getLyric 获取指定歌曲的歌词下载地址后，SDK 会触发该回调。
参数
- requestId
- 请求 ID。本次请求的唯一标识。
- songCode
- 音乐资源的编号，用于标识音乐资源。
- lyricUrl
- 歌词的下载地址。
- reason
- 音乐内容中心的请求状态码，详见 MusicContentCenterStateReason。
onMusicChartsResult
获取音乐榜单回调。
final void Function(String requestId, List<MusicChartInfo> result,
MusicContentCenterStateReason reason)? onMusicChartsResult;
当你调用 getMusicCharts 方法获取全部音乐榜单之后，SDK 会触发该回调。
参数
- requestId
- 请求 ID。本次请求的唯一标识。
- reason
- 音乐内容中心的请求状态码，详见 MusicContentCenterStateReason。
- result
- 当前可播放的音乐榜单列表。详见 MusicChartInfo。
onMusicCollectionResult
获取音乐资源列表回调。
final void Function(String requestId, MusicCollection result,
MusicContentCenterStateReason reason)? onMusicCollectionResult;
当你调用 getMusicCollectionByMusicChartId 方法来获取指定榜单的音乐资源列表或调用 searchMusic 来搜索音乐资源时，SDK 会触发此回调报告榜单中音乐资源列表的详细信息。
参数
- requestId
- 请求 ID。本次请求的唯一标识。
- reason
- 音乐内容中心的请求状态码，详见 MusicContentCenterStateReason。
- result
- 音乐资源列表的详细信息。详见 MusicCollection。
onPreLoadEvent
报告预加载音乐资源的事件。
final void Function(
String requestId,
int songCode,
int percent,
String lyricUrl,
PreloadState state,
MusicContentCenterStateReason reason)? onPreLoadEvent;
当你调用 preload 方法预加载音乐资源后，SDK 会触发该回调。
参数
- requestId
- 请求 ID。本次请求的唯一标识。
- songCode
- 音乐资源的编号，用于标识一个音乐资源。
- percent
- 音乐资源当前的加载进度，取值范围为 [0,100]。
- lyricUrl
- 歌词下载地址。
- state
- 当前音乐资源的加载状态。详见 PreloadState。
- reason
- 音乐内容中心的请求状态码，详见 MusicContentCenterStateReason。
onSongSimpleInfoResult
音乐资源的详细信息回调。
final void Function(String requestId, int songCode, String simpleInfo,
MusicContentCenterStateReason reason)? onSongSimpleInfoResult;
当你调用 getSongSimpleInfo 获取某一音乐资源的详细信息后，SDK 会触发该回调。
参数
- requestId
- 请求 ID。本次请求的唯一标识。
- songCode
- 音乐资源的编号，用于标识音乐资源。
- simpleInfo
- 音乐资源的相关信息，包含下列内容：
- 副歌片段的开始和结束的时间（ms）
- 副歌片段的歌词下载地址
- 副歌片段时长（ms）
- 歌曲名称
- 歌手名
- reason
- 音乐内容中心的请求状态码，详见 MusicContentCenterStateReason。