需要访问旧版文档站？前往旧版文档官网首页。 (在新标签页打开)
声网文档中心

版权音乐

  • Flutter

更新时间不可用

createMusicPlayer

创建音乐播放器。

Dart
Future<MusicPlayer> createMusicPlayer();

如果你需要播放音乐内容中心的音乐资源，你需要先调用该方法来创建一个音乐播放器。

返回值

  • 方法调用成功：返回 MusicPlayer 对象。
  • 方法调用失败：返回空指针。

所属接口类

destroyMusicPlayer

销毁音乐播放器对象。

Dart
Future<void> destroyMusicPlayer(MusicPlayer musicPlayer);

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

调用时机

该方法在加入频道前后均可调用，但请确保在 RtcEngine 的 release 方法前调用。

参数

参数名描述
musicPlayer

MusicPlayer 对象。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

get

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

Dart
Future<MusicChartInfo> get(int index);

参数

参数名描述
index

MusicChartInfo 数组的索引。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

MusicChartInfo，包含音乐榜单的详细信息。

所属接口类

getCaches

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

Dart
Future<List<MusicCacheInfo>> getCaches(int cacheInfoSize);

调用该方法前，你需要预先分配一定大小的内存空间用来存储缓存音乐资源的信息。如果你需要设置可缓存的音乐资源数量，可通过 initialize 的 configuration 来设置。 当你不再需要使用已缓存的音乐资源时，你需要及时释放内存以防止内存泄漏。

参数

参数名描述
cacheInfoSize

指定要获取的缓存音乐资源列表的长度。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 方法调用成功时，返回 MusicCacheInfo 对象的列表。
  • 方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

getCount

获取本次请求的音乐榜单数量。

Dart
Future<int> getCount();

返回值

本次请求的音乐榜单数量。

所属接口类

getCount

获取本次请求的音乐数量。

Dart
int getCount();

返回值

本次请求的音乐数量。

所属接口类

getInternalSongCode

创建音乐资源的副歌片段编号。

Dart
Future<int> getInternalSongCode(
      {required int songCode, required String jsonOption});

适用场景

当你需要播放某一音乐资源的副歌片段前，你需要调用此方法，通过 jsonOption 参数和该音乐资源的 songCode 来为该音乐资源的副歌片段创建一个编号，作为该资源的唯一标识。当你获取到该片段的编号后，在你调用相应方法打开、预加载、移除该资源时，将该内部歌曲编号传入 songCode 参数。

参数

参数名描述
songCode

音乐资源编号，用于标识音乐资源。你可以通过调用 getMusicCollectionByMusicChartId 或 searchMusic 方法来获取音乐资源，并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号（songCode）。

jsonOption

注： 声网会根据你在 sceneType 传入的应用场景进行收费。不同的应用场景对应不同的费率，你可以参考 计费说明 查看详细的计费。如果需要切换到不同场景，需要重新调用此方法并传入 sceneType 的值。

扩展 JSON 字段，默认为 null。目前支持传入下列值：

  • sceneType：场景类型。1：直播场景，在线 K 歌房和背景音乐播放；2：直播场景，背景音乐播放；3：（默认）声动语聊场景，在线 K 歌房；4：声动语聊场景，背景音乐播放；5：VR 场景，在线 K 歌房和背景音乐播放。示例：{"sceneType":1}。
  • highPart：副歌片段的索引，从 onMusicCollectionResult 回调中获取，索引从 0 开始。示例：{"format": {"highpart": 0}}。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • 方法调用成功，返回创建的音乐资源内部编号。
  • < 0: 方法调用失败。详见错误码了解详情和解决建议。

所属接口类

getLyric

获取音乐资源的歌词下载地址。

Dart
Future<String> getLyric({required int songCode, int lyricType = 0});

成功调用该方法后，SDK 会触发 onLyricResult 回调报告歌词的下载地址。

参数

参数名描述
songCode

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

lyricType

歌词类型：

  • 0：xml 格式。
  • 1：lrc 格式。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

一个 requestId，为本次请求的唯一标识。

所属接口类

getMusic

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

Dart
Music getMusic(int index);

参数

参数名描述
index

Music 数组的索引。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

一个 Music 实例。

所属接口类

getMusicCharts

获取全部音乐榜单。

Dart
Future<String> getMusicCharts();

当你调用该方法后，SDK 会触发 onMusicChartsResult 回调报告音乐榜单的详细信息。

返回值

一个 requestId，为本次请求的唯一标识。

所属接口类

getMusicCollectionByMusicChartId

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

Dart
Future<String> getMusicCollectionByMusicChartId(
      {required int musicChartId,
      required int page,
      required int pageSize,
      String? jsonOption});

成功调用该方法后，SDK 会触发 onMusicCollectionResult 回调报告榜单中音乐资源列表的详细信息。

参数

参数名描述
musicChartId

音乐榜单的 ID，可以通过 onMusicChartsResult 回调获取。你也可以通过 RESTful API 来获取曲库所有歌曲列表或获取增量歌曲列表。

page

当前页面编号，默认从 1 开始。

pageSize

当前音乐资源列表的总页面数量，最大值为 50。

jsonOption

扩展 JSON 字段，默认为 null。你可以通过该字段来筛选出你需要的音乐资源，目前支持筛选可打分的音乐资源及音乐资源的副歌片段：

  • pitchType：音乐资源是否支持评分。

    • 1：可评分的音乐资源。
    • 2：不可评分的音乐资源。

  • needHighPart：是否需要合唱片段资源。

    • YES：需要合唱片段资源。
    • NO：不需要合唱片段资源。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

一个 requestId，为本次请求的唯一标识。

所属接口类

getMusicContentCenter

获取 MusicContentCenter。

Dart
MusicContentCenter getMusicContentCenter()

返回值

一个 MusicContentCenter 对象。

所属接口类

getPage

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

Dart
int getPage();

返回值

当前页的页码。

所属接口类

getPageSize

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

Dart
int getPageSize();

返回值

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

所属接口类

getSongSimpleInfo

获取某一音乐资源的详细信息。

Dart
Future<String> getSongSimpleInfo(int songCode);

在调用该方法前，你需要先获取到对应的音乐资源的编号。你可以通过调用 getMusicCollectionByMusicChartId 或 searchMusic 方法来获取音乐资源，并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号（songCode）。 当你调用该方法后，SDK 会触发 onSongSimpleInfoResult 回调报告音乐资源的详细信息。

参数

参数名描述
songCode

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

一个 requestId，为本次请求的唯一标识。

所属接口类

getTotal

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

Dart
int getTotal();

返回值

列表内音乐资源的总数量。

所属接口类

initialize

初始化 MusicContentCenter。

Dart
Future<void> initialize(MusicContentCenterConfiguration configuration);

在调用 MusicContentCenter 类下的其他方法前，你需要先调用该方法初始化 MusicContentCenter。

参数

参数名描述
configuration

MusicContentCenter 的设置，详见 MusicContentCenterConfiguration。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

isPreloaded

检测音乐资源是否已被预加载。

Dart
Future<bool> isPreloaded(int songCode);

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

参数

参数名描述
songCode

音乐资源的编号，用于标识一个音乐资源。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

  • true：该音乐资源已被预加载。
  • false：该音乐资源未被预加载。

所属接口类

openWithSongCode

通过音乐资源编号打开音乐资源。

Dart
Future<void> openWithSongCode({required int songCode, int startPos = 0});

在调用此方法之前，请确保需要播放的音乐资源已加载完成。你可以调用 isPreloaded 方法来检测音乐资源是否已被预加载，或通过 onPreLoadEvent 回调得知。 调用该方法后会触发 onPlayerSourceStateChanged 回调。在收到报告播放状态为 playerStateOpenCompleted 后，你可以调用 play 方法播放媒体文件。

注： 如果你想要打开的音乐资源受数字版权保护，则需要调用此方法打开。对于不受数字版权保护的音乐资源，你可以选择通过调用此方法或 MediaPlayer 类下的 open 方法来打开。

参数

参数名描述
songCode

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

startPos

设置起始播放位置（毫秒），默认值为 0。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

preload

预加载音乐资源。

Dart
Future<String> preload(int songCode);

你可以调用该方法预先加载需要播放的音乐资源。成功调用该方法后，SDK 会触发 onPreLoadEvent 回调报告预加载音乐资源的事件。 在调用该方法来预加载音乐资源之前，你需要调用 getMusicCollectionByMusicChartId 或 searchMusic 方法来获取你需要播放的音乐资源，并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号（songCode）。

注： 如需销毁 RtcEngine 对象，请在收到 onPreLoadEvent 回调后，再调用 release 方法。

参数

参数名描述
songCode

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

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

一个 requestId，为本次请求的唯一标识。

所属接口类

registerEventHandler

注册音乐内容中心回调事件。

Dart
void registerEventHandler(MusicContentCenterEventHandler eventHandler);

参数

参数名描述
eventHandler

待注册的回调事件，详见 MusicContentCenterEventHandler。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

release

释放音乐内容中心所占用的所有资源。

Dart
Future<void> release();

该方法需要在 RtcEngine 的 release 方法前调用。

所属接口类

removeCache

删除已缓存的音乐资源。

Dart
Future<void> removeCache(int songCode);

你可以调用该方法删除某一已缓存的音乐资源，如需删除多个音乐资源，你可以多次调用该方法。

参数

参数名描述
songCode

待删除的音乐资源的编号。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

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

所属接口类

renewToken

更新 Token。

Dart
Future<void> renewToken(String token);

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

参数

参数名描述
token

新的 Token。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

searchMusic

搜索音乐资源。

Dart
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

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

Dart
Future<void> setPlayMode(MusicPlayMode mode);

你可以调用该方法来设置启用原唱、伴奏或导唱。如不调用该方法进行设置，则默认播放伴奏；如果音乐资源没有伴奏，则播放原唱。

注： 你可以通过 onMusicCollectionResult 回调获取音乐资源的详细信息，并可通过其中的 result 参数得知需播放的版权音乐所支持的播放类型。

适用场景

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

调用时机

该方法需要在 createMusicPlayer 之后调用。

参数

参数名描述
mode

播放模式，详见 MusicPlayMode。

表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

unregisterEventHandler

取消注册音乐内容中心事件回调。

Dart
void unregisterEventHandler();

返回值

方法成功调用时，无返回值；方法调用失败时，会抛出 AgoraRtcException 异常，你需要捕获异常并进行处理。详见错误码了解详情和解决建议。

所属接口类

onLyricResult

歌词下载地址回调。

Dart
final void Function(String requestId, int songCode, String lyricUrl,
    MusicContentCenterStateReason reason)? onLyricResult;

当你调用 getLyric 获取指定歌曲的歌词下载地址后，SDK 会触发该回调。

参数

参数名描述
requestId

请求 ID。本次请求的唯一标识。

songCode

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

lyricUrl

歌词的下载地址。

reason

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

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onMusicChartsResult

获取音乐榜单回调。

Dart
final void Function(String requestId, List<MusicChartInfo> result,
    MusicContentCenterStateReason reason)? onMusicChartsResult;

当你调用 getMusicCharts 方法获取全部音乐榜单之后，SDK 会触发该回调。

参数

参数名描述
requestId

请求 ID。本次请求的唯一标识。

reason

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

result

当前可播放的音乐榜单列表。详见 MusicChartInfo。

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onMusicCollectionResult

获取音乐资源列表回调。

Dart
final void Function(String requestId, MusicCollection result,
    MusicContentCenterStateReason reason)? onMusicCollectionResult;

当你调用 getMusicCollectionByMusicChartId 方法来获取指定榜单的音乐资源列表或调用 searchMusic 来搜索音乐资源时，SDK 会触发此回调报告榜单中音乐资源列表的详细信息。

参数

参数名描述
requestId

请求 ID。本次请求的唯一标识。

reason

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

result

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

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

onPreLoadEvent

报告预加载音乐资源的事件。

Dart
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

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

Dart
final void Function(String requestId, int songCode, String simpleInfo,
    MusicContentCenterStateReason reason)? onSongSimpleInfoResult;

当你调用 getSongSimpleInfo 获取某一音乐资源的详细信息后，SDK 会触发该回调。

参数

参数名描述
requestId

请求 ID。本次请求的唯一标识。

songCode

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

simpleInfo

音乐资源的相关信息，包含下列内容：

  • 副歌片段的开始和结束的时间（ms）
  • 副歌片段的歌词下载地址
  • 副歌片段时长（ms）
  • 歌曲名称
  • 歌手名
reason

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

表格内容超出当前宽度，可横向滚动查看更多列。

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利