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

版权音乐

  • React Native

更新时间不可用

createMusicPlayer

创建音乐播放器。

TypeScript
abstract createMusicPlayer(): IMusicPlayer;

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

返回值

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

所属接口类

destroyMusicPlayer

销毁音乐播放器对象。

TypeScript
abstract destroyMusicPlayer(musicPlayer: IMusicPlayer): number;

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

调用时机

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

参数

参数名描述
musicPlayer

IMusicPlayer 对象。

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

返回值

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

所属接口类

get

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

TypeScript
abstract get(index: number): MusicChartInfo;

参数

参数名描述
index

MusicChartInfo 数组的索引。

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

返回值

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

所属接口类

getCaches

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

TypeScript
abstract getCaches(): { cacheInfo: MusicCacheInfo[]; cacheInfoSize: number };

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

返回值

方法调用成功时，返回一个包含以下属性的对象：

  • cacheInfo：音乐缓存信息数组。
  • cacheInfoSize：音乐缓存信息数组的长度。

所属接口类

getCount

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

TypeScript
abstract getCount(): number;

返回值

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

所属接口类

getCount

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

TypeScript
abstract getCount(): number;

返回值

本次请求的音乐数量。

所属接口类

getInternalSongCode

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

TypeScript
abstract getInternalSongCode(songCode: number, jsonOption: string): number;

适用场景

当你需要播放某一音乐资源的副歌片段前，你需要调用此方法，通过 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

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

TypeScript
abstract getLyric(songCode: number, lyricType?: number): string;

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

参数

参数名描述
songCode

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

lyricType

歌词类型：

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

返回值

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

所属接口类

getMusic

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

TypeScript
abstract getMusic(index: number): Music;

参数

参数名描述
index

Music 数组的索引。

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

返回值

一个 Music 实例。

所属接口类

getMusicCharts

获取全部音乐榜单。

TypeScript
abstract getMusicCharts(): string;

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

返回值

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

所属接口类

getMusicCollectionByMusicChartId

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

TypeScript
abstract getMusicCollectionByMusicChartId(
    musicChartId: number,
    page: number,
    pageSize: number,
    jsonOption?: string
  ): string;

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

参数

参数名描述
musicChartId

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

page

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

pageSize

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

jsonOption

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

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

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

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

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

返回值

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

所属接口类

getMusicContentCenter

获取 IMusicContentCenter。

TypeScript
abstract getMusicContentCenter(): IMusicContentCenter;

返回值

一个 IMusicContentCenter 对象。

所属接口类

getPage

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

TypeScript
abstract getPage(): number;

返回值

当前页的页码。

所属接口类

getPageSize

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

TypeScript
virtual int getPageSize() = 0;

返回值

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

所属接口类

getSongSimpleInfo

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

TypeScript
abstract getSongSimpleInfo(songCode: number): string;

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

参数

参数名描述
songCode

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

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

返回值

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

所属接口类

getTotal

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

TypeScript
abstract getTotal(): number;

返回值

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

所属接口类

initialize

初始化 IMusicContentCenter。

TypeScript
abstract initialize(configuration: MusicContentCenterConfiguration): number;

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

参数

参数名描述
configuration

IMusicContentCenter 的设置，详见 MusicContentCenterConfiguration。

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

返回值

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

所属接口类

isPreloaded

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

TypeScript
abstract isPreloaded(songCode: number): number;

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

参数

参数名描述
songCode

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

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

返回值

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

所属接口类

openWithSongCode

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

TypeScript
abstract openWithSongCode(songCode: number, startPos?: number): number;

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

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

参数

参数名描述
songCode

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

startPos

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

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

返回值

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

所属接口类

Preload

预加载音乐资源。

TypeScript
abstract preload(songCode: number): string;

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

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

参数

参数名描述
songCode

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

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

返回值

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

所属接口类

registerEventHandler

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

TypeScript
abstract registerEventHandler(
    eventHandler: IMusicContentCenterEventHandler
  ): number;

参数

参数名描述
eventHandler

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

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

返回值

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

所属接口类

release

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

TypeScript
abstract release(): void;

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

所属接口类

removeCache

删除已缓存的音乐资源。

TypeScript
abstract removeCache(songCode: number): number;

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

参数

参数名描述
songCode

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

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

返回值

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

所属接口类

renewToken

更新 Token。

TypeScript
abstract renewToken(token: string): number;

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

参数

参数名描述
token

新的 Token。

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

返回值

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

所属接口类

searchMusic

搜索音乐资源。

TypeScript
abstract searchMusic(
    requestId: string,
    keyWord: string,
    page: number,
    pageSize: number,
    jsonOption?: string
  ): number;

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

参数

参数名描述
keyword

搜索关键词，支持歌曲名、歌手搜索。

page

想要获取的音乐资源列表的目标页编号。

pageSize

每页所展示的音乐资源的最大数量，最大值为 50。

jsonOption

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

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

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

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

    • YES：需要合唱片段资源。
    • NO：不需要合唱片段资源。
requestId

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

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

返回值

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

所属接口类

setPlayMode

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

TypeScript
abstract setPlayMode(mode: MusicPlayMode): number;

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

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

适用场景

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

调用时机

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

参数

参数名描述
mode

播放模式，详见 MusicPlayMode。

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

返回值

  • 0: 方法调用成功。

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

    • -2: 参数设置错误，请重新设置参数。

所属接口类

unregisterEventHandler

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

TypeScript
abstract unregisterEventHandler(): number;

返回值

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

所属接口类

onLyricResult

歌词下载地址回调。

TypeScript
onLyricResult?(
    requestId: string,
    songCode: number,
    lyricUrl: string,
    reason: MusicContentCenterStateReason
  ): void;

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

参数

参数名描述
requestId

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

songCode

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

lyricUrl

歌词的下载地址。

reason

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

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

所属接口类

onMusicChartsResult

获取音乐榜单回调。

TypeScript
onMusicChartsResult?(
    requestId: string,
    result: MusicChartInfo[],
    reason: MusicContentCenterStateReason
  ): void;

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

参数

参数名描述
requestId

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

reason

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

result

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

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

所属接口类

onMusicCollectionResult

获取音乐资源列表回调。

TypeScript
onMusicCollectionResult?(
    requestId: string,
    result: MusicCollection,
    reason: MusicContentCenterStateReason
  ): void;

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

参数

参数名描述
requestId

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

reason

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

result

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

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

所属接口类

onPreLoadEvent

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

TypeScript
onPreLoadEvent?(
    requestId: string,
    songCode: number,
    percent: number,
    lyricUrl: string,
    status: PreloadState,
    reason: MusicContentCenterStateReason
  ): void;

当你调用 Preload 方法预加载音乐资源后，SDK 会触发该回调。

参数

参数名描述
requestId

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

songCode

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

percent

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

lyricUrl

歌词下载地址。

state

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

reason

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

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

所属接口类

onSongSimpleInfoResult

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

TypeScript
onSongSimpleInfoResult?(
    requestId: string,
    songCode: number,
    simpleInfo: string,
    reason: MusicContentCenterStateReason
  ): void;

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

参数

参数名描述
requestId

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

songCode

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

simpleInfo

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

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

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

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

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利