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

版权音乐

  • iOS

更新时间不可用

createMusicPlayerWithDelegate:

创建一个音乐播放器。

Objective-C
- (id<AgoraMusicPlayerProtocol> _Nullable)createMusicPlayerWithDelegate:(id<AgoraRtcMediaPlayerDelegate> _Nullable)delegate NS_SWIFT_NAME(createMusicPlayer(delegate:));

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

参数

参数名描述
delegate

播放器事件回调接口，详见 AgoraRtcMediaPlayerDelegate。

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

返回值

所属接口类

destroy

销毁 AgoraMusicContentCenter 实例。

Objective-C
+ (void)destroy;

你必须在调用 destroy 方法之前，先调用此方法。

所属接口类

destroyMusicPlayer:

销毁音乐播放器对象。

Objective-C
- (NSInteger)destroyMusicPlayer:(id<AgoraMusicPlayerProtocol>)musicPlayer;

当你不再需要使用音乐播放器时，可以调用此方法销毁音乐播放器对象。如果在销毁后需要再次使用音乐播放器，必须调用 createMusicPlayerWithDelegate: 方法重新创建一个新的音乐播放器对象。

调用时机

你可以在加入频道前或后调用此方法，但必须确保在调用 destroy [2/2] 方法之前调用。

参数

参数名描述
musicPlayer

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

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

返回值

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

所属接口类

enableMainQueueDispatch:

设置是否将回调方法派发到主线程。

Objective-C
- (void)enableMainQueueDispatch:(BOOL)enabled;

如果你不将回调方法派发到主线程，你需要手动将 UI 操作派发到主线程。

参数

参数名描述
enabled

YES：将回调方法派发到主线程。 NO：（默认）不将回调方法派发到主线程。

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

所属接口类

getCaches

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

Objective-C
- (NSArray *)getCaches NS_SWIFT_NAME(getCaches());

在调用此方法前，你需要分配足够的内存来存储缓存音乐资源的信息。如果你想设置可缓存的音乐资源数量，可以通过 sharedContentCenterWithConfig: 方法中的 config 参数进行配置。当你不再需要缓存的音乐资源时，应及时释放内存以防止内存泄漏。

返回值

  • 方法调用成功，返回包含 AgoraMusicCacheInfo 对象的数组。
  • 方法调用失败，返回 nil。

所属接口类

getInternalSongCode:jsonOption:

创建音乐资源副歌片段的内部 ID。

Objective-C
- (NSInteger)getInternalSongCode:(NSInteger)songCode jsonOption:(NSString * _Nullable)jsonOption  NS_SWIFT_NAME(getInternalSongCode(songCode:jsonOption:));

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

参数

参数名描述
songCode

音乐资源的唯一标识。你可以通过调用 getMusicCollectionWithMusicChartId:page:pageSize:jsonOption: 或 searchMusicWithKeyWord:page:pageSize:jsonOption: 方法，并从 onMusicCollectionResult:result:reason: 回调中获取 songCode。

jsonOption

注： 声网会根据你在 sceneType 中指定的频道场景计费。不同的频道场景对应不同的计费标准，详见计费文档。若需切换频道场景，必须重新调用该方法并传入新的 sceneType 值。

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

  • sceneType：频道场景。

    • 1：直播场景：在线 K 歌房和背景音乐播放。
    • 2：直播场景：背景音乐播放。
    • 3：（默认）语聊场景：在线 K 歌房。
    • 4：语聊场景：背景音乐播放。
    • 5：VR 场景：在线 K 歌房和背景音乐播放。示例：{"sceneType":1}

  • highPart：副歌片段的索引。你可以从 onMusicCollectionResult:result:reason: 回调中获取该索引并传入。索引从 0 开始。示例：{"format": {"highpart": 0}}

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

返回值

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

所属接口类

getLyricWithSongCode:lyricType:

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

Objective-C
- (NSString *)getLyricWithSongCode:(NSInteger)songCode lyricType:(NSInteger)lyricType NS_SWIFT_NAME(getLyric(songCode:lyricType:));

调用该方法后，SDK 会触发 onLyricResult:songCode:lyricUrl:reason: 回调，返回歌词的下载链接。

相关回调

成功调用该方法后，SDK 会触发 onLyricResult:songCode:lyricUrl:reason: 回调，报告歌词的下载链接。

参数

参数名描述
songCode

音乐资源的标识符，用于指定音乐资源。

lyricType

歌词的类型：

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

返回值

  • 方法调用成功时，返回请求 ID，用于标识该请求的唯一性。
  • 方法调用失败时，返回空字符串。

所属接口类

getMusicCharts

获取所有音乐排行榜。

Objective-C
- (NSString *)getMusicCharts;

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

相关回调

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

返回值

方法调用成功时，返回一个唯一标识该请求的 requestId。

所属接口类

getMusicCollectionWithMusicChartId:page:pageSize:jsonOption:

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

Objective-C
- (NSString *)getMusicCollectionWithMusicChartId:(NSInteger)musicChartId page:(NSInteger)page pageSize:(NSInteger)pageSize jsonOption:(NSString * _Nullable)jsonOption NS_SWIFT_NAME(getMusicCollection(musicChartId:page:pageSize:jsonOption:));

相关回调

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

参数

参数名描述
musicChartId

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

page

当前页码，默认从 1 开始。

pageSize

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

jsonOption

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

  • pitchType：是否支持评分。

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

  • needHighPart：是否需要副歌片段资源。

    • true：需要副歌片段资源。
    • false：不需要副歌片段资源。
表格内容超出当前宽度，可横向滚动查看更多列。

返回值

方法调用成功时，返回唯一标识该请求的 requestId。

所属接口类

getSongSimpleInfoWithSongCode:

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

Objective-C
- (NSString *)getSongSimpleInfoWithSongCode:(NSInteger)songCode NS_SWIFT_NAME(getSongSimpleInfo(songCode:));

在调用该方法前，你需要先获取对应音乐资源的标识符。你可以通过调用 getMusicCollectionWithMusicChartId:page:pageSize:jsonOption: 或 searchMusicWithKeyWord:page:pageSize:jsonOption: 方法获取音乐资源，并通过这些方法触发的 onMusicCollectionResult:result:reason: 回调获取音乐资源标识符（songCode）。

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

参数

参数名描述
songCode

音乐资源的标识符，用于指定音乐资源。

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

返回值

方法调用成功时，返回唯一标识此次请求的 requestId。

所属接口类

sharedContentCenterWithConfig:

初始化 AgoraMusicContentCenter。

Objective-C
+ (instancetype _Nullable)sharedContentCenterWithConfig:(AgoraMusicContentCenterConfig *)config NS_SWIFT_NAME(sharedContentCenter(config:));

你必须先调用该方法初始化 AgoraMusicContentCenter，然后才能调用该类中的其他方法。

参数

参数名描述
config

用于初始化 AgoraMusicContentCenter 的配置，详见 AgoraMusicContentCenterConfig。

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

返回值

所属接口类

isPreloadedWithSongCode:

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

Objective-C
- (NSInteger)isPreloadedWithSongCode:(NSInteger)songCode NS_SWIFT_NAME(isPreloaded(songCode:));

该方法为同步调用。你可以调用 preloadWithSongCode: 方法来预加载新的音乐资源。

参数

参数名描述
songCode

用于指定特定音乐资源的音乐资源标识符。

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

返回值

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

所属接口类

openMediaWithSongCode:startPos:

通过资源 ID 打开音乐资源。

Objective-C
- (NSInteger)openMediaWithSongCode:(NSInteger)songCode startPos:(NSInteger)startPos NS_SWIFT_NAME(openMedia(songCode:startPos:));

调用该方法前，请确保要播放的音乐资源已加载完成。你可以通过调用 isPreloadedWithSongCode: 方法，或监听 onPreLoadEvent 回调来确认音乐资源是否已预加载。

调用该方法后，SDK 会触发 AgoraRtcMediaPlayer:didChangedToState:reason: 回调。当你收到播放状态 AgoraMediaPlayerStateOpenCompleted 后，可以调用 play 方法开始播放。

注： 如果要打开的音乐资源受数字版权保护，必须使用该方法。对于未受数字版权保护的音乐资源，你可以选择使用该方法或 open:startPos: 方法打开。

参数

参数名描述
songCode

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

startPos

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

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

返回值

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

所属接口类

preloadWithSongCode:jsonOption:

预加载音乐资源。

Objective-C
- (NSInteger)preloadWithSongCode:(NSInteger)songCode jsonOption:(NSString* _Nullable)jsonOption NS_SWIFT_NAME(preload(songCode:jsonOption:))  __attribute__((deprecated("Use preload(songCode:) instead.")));

废弃

该方法已废弃，请改用 preload(songCode:)。

你可以调用此方法预加载你想播放的音乐资源。

注： 在销毁 AgoraRtcEngineKit 对象前，请确保等待 onPreLoadEvent:songCode:percent:lyricUrl:state:reason: 回调后再调用 destroy 方法。

相关回调

成功调用该方法后，SDK 会触发 onPreLoadEvent:songCode:percent:lyricUrl:state:reason: 回调报告预加载音乐资源的事件。

参数

参数名描述
songCode

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

jsonOption

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

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

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

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

返回值

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

所属接口类

preloadWithSongCode:

预加载音乐资源。

Objective-C
- (NSString *)preloadWithSongCode:(NSInteger)songCode NS_SWIFT_NAME(preload(songCode:));

你可以调用此方法预加载你想播放的音乐资源。调用成功后，SDK 会触发 onPreLoadEvent:songCode:percent:lyricUrl:state:reason: 回调，报告音乐资源的预加载事件。

注： 在销毁 AgoraRtcEngineKit 对象前，必须等待收到 onPreLoadEvent:songCode:percent:lyricUrl:state:reason: 回调后再调用 destroy 方法。

相关回调

成功调用该方法后，SDK 会触发 onPreLoadEvent:songCode:percent:lyricUrl:state:reason: 回调报告音乐资源的预加载事件。调用此方法前，你需要先调用 getMusicCollectionWithMusicChartId:page:pageSize:jsonOption: 或 searchMusicWithKeyWord:page:pageSize:jsonOption: 获取你想播放的音乐资源，并从这些方法触发的 onMusicCollectionResult:result:reason: 回调中获取歌曲编号（songCode）。

参数

参数名描述
songCode

音乐资源的标识符。

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

返回值

  • 方法调用成功时，返回请求 ID，用于唯一标识该请求。
  • 方法调用失败时，返回空字符串。

所属接口类

registerEventDelegate:

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

Objective-C
- (NSInteger)registerEventDelegate:(id<AgoraMusicContentCenterEventDelegate> _Nullable)eventDelegate;

参数

参数名描述
eventDelegate

要注册的回调事件。如果你想移除之前注册的回调事件，请传入 nil。详见 AgoraMusicContentCenterEventDelegate。

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

返回值

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

所属接口类

removeCacheWithSongCode:

删除已缓存的音乐资源。

Objective-C
- (NSInteger)removeCacheWithSongCode:(NSInteger)songCode NS_SWIFT_NAME(removeCache(songCode:));

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

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

参数

参数名描述
songCode

要删除的音乐资源的标识符。

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

返回值

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

所属接口类

renewToken:

更新用于鉴权的 Token。

Objective-C
- (NSInteger)renewToken:(NSString * _Nonnull)token;

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

参数

参数名描述
token

新的 Token。

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

返回值

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

所属接口类

searchMusicWithKeyWord:page:pageSize:jsonOption:

搜索音乐资源。

Objective-C
- (NSString *)searchMusicWithKeyWord:(NSString *)keyWord page:(NSInteger)page pageSize:(NSInteger)pageSize jsonOption:(NSString * _Nullable)jsonOption NS_SWIFT_NAME(searchMusic(keyWord:page:pageSize:jsonOption:));

调用该方法后，SDK 会触发 onMusicCollectionResult:result:reason: 回调，返回检索到的音乐资源列表。

参数

参数名描述
keyWord

搜索关键词。支持按歌曲标题或歌手名搜索。

page

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

pageSize

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

jsonOption

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

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

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

示例：{"pitchType":1}。

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

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

示例：{"needHighPart":true}。

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

返回值

  • 方法调用成功时，返回请求 ID，用于标识此次请求的唯一标识符。
  • 方法调用失败时，返回空字符串。

所属接口类

setPlayMode:

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

Objective-C
- (NSInteger)setPlayMode:(AgoraMusicPlayMode)mode NS_SWIFT_NAME(setPlayMode(mode:));

你可以调用此方法启用原唱、人声伴奏或导唱。如果不调用此方法，默认播放人声伴奏。如果音乐资源不包含人声伴奏，则播放原唱。

注： 你可以通过 onMusicCollectionResult 回调获取音乐资源的详细信息。从 result 参数中可以了解该版权音乐支持哪些播放模式。

适用场景

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

调用时机

你必须在调用 createMusicPlayerWithDelegate: 方法之后调用此方法。

参数

参数名描述
mode

播放模式，详见 AgoraMusicPlayMode。

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

返回值

  • 0：方法调用成功。

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

    • -2：参数无效。请重新设置参数。

所属接口类

onLyricResult:songCode:lyricUrl:reason:

歌词下载链接的回调。

Objective-C
- (void)onLyricResult:(NSString*)requestId songCode:(NSInteger)songCode lyricUrl:(NSString* _Nullable)lyricUrl reason:(AgoraMusicContentCenterStateReason)reason;

调用 getLyricWithSongCode:lyricType: 方法获取指定歌曲的歌词下载链接后，SDK 会触发该回调。

触发时机

该回调在你调用 getLyricWithSongCode:lyricType: 获取指定歌曲的歌词下载链接后被触发。

参数

参数名描述
requestId

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

songCode

音乐资源的标识符，用于指定音乐资源。

lyricUrl

歌词的下载链接。

reason

请求状态码，详见 AgoraMusicContentCenterStateReason。

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

所属接口类

onMusicChartsResult:result:reason:

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

Objective-C
- (void)onMusicChartsResult:(NSString *)requestId result:(NSArray<AgoraMusicChartInfo*> *)result reason:(AgoraMusicContentCenterStateReason)reason;

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

触发时机

该回调在你调用 getMusicCharts 方法后被触发。

参数

参数名描述
requestId

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

result

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

reason

请求的状态码。详见 AgoraMusicContentCenterStateReason。

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

所属接口类

onMusicCollectionResult:result:reason:

获取音乐内容列表的回调。

Objective-C
- (void)onMusicCollectionResult:(NSString *)requestId result:(AgoraMusicCollection *)result reason:(AgoraMusicContentCenterStateReason)reason;

当你调用 getMusicCollectionWithMusicChartId:page:pageSize:jsonOption: 或 searchMusicWithKeyWord:page:pageSize:jsonOption: 方法获取指定榜单或搜索音乐内容时，SDK 会触发该回调，返回音乐内容列表的详细信息。

触发时机

该回调在你调用 getMusicCollectionWithMusicChartId:page:pageSize:jsonOption: 或 searchMusicWithKeyWord:page:pageSize:jsonOption: 后被触发。

参数

参数名描述
requestId

请求 ID。此请求的唯一标识符。

result

音乐内容列表的详细信息。详见 AgoraMusicCollection。

reason

请求状态码。详见 AgoraMusicContentCenterStateReason。

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

所属接口类

onPreLoadEvent:songCode:percent:lyricUrl:state:reason:

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

Objective-C
- (void)onPreLoadEvent:(NSString*)requestId songCode:(NSInteger)songCode percent:(NSInteger)percent lyricUrl:(NSString * _Nullable)lyricUrl state:(AgoraMusicContentCenterPreloadState)state reason:(AgoraMusicContentCenterStateReason)reason;

调用 preloadWithSongCode:jsonOption: 或 preloadWithSongCode: 方法预加载音乐资源后，SDK 会触发该回调。

触发时机

该回调在调用 preloadWithSongCode:jsonOption: 或 preloadWithSongCode: 方法预加载音乐资源后被触发。

参数

参数名描述
requestId

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

songCode

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

percent

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

lyricUrl

歌词的下载地址。

state

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

reason

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

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

所属接口类

onSongSimpleInfoResult:songCode:simpleInfo:reason:

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

Objective-C
- (void)onSongSimpleInfoResult:(NSString*)requestId songCode:(NSInteger)songCode simpleInfo:(NSString* _Nullable)simpleInfo reason:(AgoraMusicContentCenterStateReason)reason;

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

触发时机

该回调在你调用 getSongSimpleInfoWithSongCode: 获取音乐资源详细信息后被触发。

参数

参数名描述
requestId

请求 ID。该请求的唯一标识符。

songCode

音乐资源的标识符。

simpleInfo

音乐资源的相关信息，包括：

  • 副歌片段的起始和结束时间（毫秒）。
  • 副歌片段的歌词下载 URL。
  • 副歌片段的时长（毫秒）。
  • 歌曲名称。
  • 歌手名称。
reason

请求状态码，详见 AgoraMusicContentCenterStateReason。

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

所属接口类

咨询电话

400 632 6626

上海声网科技有限公司

Copyright © 2026 声网保留所有权利