版权音乐

createMusicPlayerWithDelegate:

创建音乐播放器。

Objective-C

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

详情

自从

v4.1.0

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

参数

delegate

详见 AgoraRtcMediaPlayerDelegate。

返回值

• 方法调用成功：返回 AgoraMusicPlayerProtocol 实例。
• 方法调用失败：返回空指针。

所属接口类

• AgoraMusicContentCenter

destroyMusicPlayer:

销毁音乐播放器对象。

Objective-C

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

自从

v4.4.0

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

调用时机

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

调用限制

无。

参数

musicPlayer

AgoraMusicPlayerProtocol 对象。

返回值

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

所属接口类

• AgoraMusicContentCenter

destroy

销毁 AgoraMusicContentCenter 实例。

Objective-C

+ (void)destroy;

详情

自从

v4.1.0

该方法需要在 AgoraRtcEngineKit 的 destroy 方法前调用。

所属接口类

• AgoraMusicContentCenter

enableMainQueueDispatch:

是否分发回调至主队列。

Objective-C

- (void)enableMainQueueDispatch:(BOOL)enabled;

详情

自从

v4.1.0

如果不分发回调方法到主队列，App 应将 UI 操作分发到主队列。

参数

enabled

• YES：分发回调方法到主队列。
• NO：（默认）不分发回调方法到主队列。

返回值

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

所属接口类

• AgoraMusicContentCenter

getCaches

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

Objective-C

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

详情

自从

v4.2.0

调用该方法前，你需要预先分配一定大小的内存空间用来存储缓存音乐资源的信息。如果你需要设置可缓存的音乐资源数量，可通过 sharedContentCenterWithConfig: 的 config 来设置。

当你不再需要使用已缓存的音乐资源时，你需要及时释放内存以防止内存泄漏。

返回值

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

所属接口类

• AgoraMusicContentCenter

getInternalSongCode:jsonOption:

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

Objective-C

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

自从

v4.2.2

适用场景

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

参数

songCode

音乐资源编号，用于标识音乐资源。你可以通过调用 getMusicCollectionWithMusicChartId:page:pageSize:jsonOption: 或 searchMusicWithKeyWord:page:pageSize:jsonOption: 方法来获取音乐资源，并通过由此触发的 onMusicCollectionResult:result:reason: 回调获取音乐资源的编号（songCode）。

jsonOption

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

Key 值	Value 值	示例
sceneType	场景类型： 1：直播场景：K 歌及背景音乐播放。 2：直播场景：背景音乐播放。 3：（默认）语聊场景：K 歌。 4：语聊场景：背景音乐播放。 5：VR 场景：K 歌及背景音乐播放。 信息 声网会根据你在 sceneType 传入的应用场景进行收费。不同的应用场景对应不同的费率，你可以参考 计费说明 查看详细的计费。如果需要切换到不同场景，需要重新调用此方法并传入 sceneType 的值。	{"sceneType":1}
highPart	副歌片段的索引。你可以从 onMusicCollectionResult:result:reason: 回调中获取副歌片段的索引然后传值。索引序号从 0 开始。	{"format": {"highpart": 0}}

返回值

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

所属接口类

• AgoraMusicContentCenter

getLyricWithSongCode:lyricType:

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

Objective-C

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

详情

自从

v4.1.0

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

参数

songCode

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

lyricType

歌词类型：

• 0：xml 格式。
• 1：lrc 格式。

返回值

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

所属接口类

• AgoraMusicContentCenter

getMusicCharts

获取全部音乐榜单。

Objective-C

- (NSString *)getMusicCharts;

详情

自从

v4.1.0

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

返回值

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

所属接口类

• AgoraMusicContentCenter

getMusicCollectionWithMusicChartId:page:pageSize:jsonOption:

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

Objective-C

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

详情

自从

v4.1.0

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

参数

musicChartId

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

page

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

pageSize

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

jsonOption

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

Key 值	Value 值	示例
pitchType	是否支持打分： 1：支持打分的音乐资源。 2：不支持打分的音乐资源。	{"pitchType":1}
needHighPart	是否需要副歌片段资源： YES：需要副歌片段资源。 NO：不需要副歌片段资源。	{"needHighPart":true}

返回值

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

所属接口类

• AgoraMusicContentCenter

getSongSimpleInfoWithSongCode:

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

Objective-C

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

详情

自从

v4.2.2

在调用该方法前，你需要先获取到对应的音乐资源的编号。你可以通过调用 getMusicCollectionWithMusicChartId:page:pageSize:jsonOption: 或 searchMusicWithKeyWord:page:pageSize:jsonOption: 方法来获取音乐资源，并通过由此触发的 onMusicCollectionResult:result:reason: 回调获取音乐资源的编号（songCode）。

当你调用该方法后，SDK 会触发 onSongSimpleInfoResult:songCode:simpleInfo:reason: 回调报告音乐资源的详细信息。

参数

songCode

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

返回值

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

所属接口类

• AgoraMusicContentCenter

sharedContentCenterWithConfig:

初始化 AgoraMusicContentCenter。

Objective-C

+ (instancetype)sharedContentCenterWithConfig:(AgoraMusicContentCenterConfig *)config NS_SWIFT_NAME(sharedContentCenter(config:));

详情

自从

v4.1.0

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

参数

config

AgoraMusicContentCenter 的设置，详见 AgoraMusicContentCenterConfig。

返回值

• 方法调用成功，返回一个 AgoraMusicContentCenter 实例。
• 方法调用失败，返回 nil。

所属接口类

• AgoraMusicContentCenter

isPreloadedWithSongCode:

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

Objective-C

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

详情

自从

v4.1.0

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

参数

songCode

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

返回值

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

所属接口类

• AgoraMusicContentCenter

preloadWithSongCode:jsonOption:

预加载音乐资源。

Objective-C

- (NSInteger)preloadWithSongCode:(NSInteger)songCode jsonOption:(NSString* _Nullable)jsonOption NS_SWIFT_NAME(preload(songCode:jsonOption:));

详情

废弃

该方法已废弃，请改用 preloadWithSongCode:。

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

在调用该方法来预加载音乐资源之前，你需要调用 getMusicCollectionWithMusicChartId:page:pageSize:jsonOption: 或 searchMusicWithKeyWord:page:pageSize:jsonOption: 方法来获取你需要播放的音乐资源，并通过由此触发的 onMusicCollectionResult:result:reason: 回调获取音乐资源的编号（songCode）。

注意

如需销毁 AgoraRtcEngineKit 对象，请在收到 onPreLoadEvent:songCode:percent:lyricUrl:state:reason: 回调后，再调用 destroy 方法。

参数

songCode

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

jsonOption

扩展 JSON 字段。

声网会根据你在场景字段（sceneType）传入的应用场景进行收费。不同的应用场景对应不同的费率，你可以参考 计费说明 查看详细的计费。

• 1：直播场景：K 歌及背景音乐播放。
• 2：直播场景：背景音乐播放。
• 3：（默认）语聊场景：K 歌。
• 4：语聊场景：背景音乐播放。
• 5：VR 场景：K 歌及背景音乐播放。

如果需要切换到不同场景，需要重新调用此方法并在该字段中传入 sceneType 的值。

示例：{"sceneType":1}

返回值

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

所属接口类

• AgoraMusicContentCenter

preloadWithSongCode:

预加载音乐资源。

Objective-C

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

详情

自从

v4.2.2

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

在调用该方法来预加载音乐资源之前，你需要调用 getMusicCollectionWithMusicChartId:page:pageSize:jsonOption: 或 searchMusicWithKeyWord:page:pageSize:jsonOption: 方法来获取你需要播放的音乐资源，并通过由此触发的 onMusicCollectionResult:result:reason: 回调获取音乐资源的编号（songCode）。

注意

如需销毁 AgoraRtcEngineKit 对象，请在收到 onPreLoadEvent:songCode:percent:lyricUrl:state:reason: 回调后，再调用 destroy 方法。

参数

songCode

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

返回值

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

所属接口类

• AgoraMusicContentCenter

registerEventDelegate:

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

Objective-C

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

详情

自从

v4.1.0

参数

eventDelegate

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

返回值

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

所属接口类

• AgoraMusicContentCenter

removeCacheWithSongCode:

删除已缓存的音乐资源。

Objective-C

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

详情

自从

v4.2.0

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

信息

该方法不会删除正在播放中的已缓存音乐资源。

参数

songCode

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

返回值

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

所属接口类

• AgoraMusicContentCenter

renewToken:

更新 Token。

Objective-C

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

详情

自从

v4.1.0

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

参数

token

新的 Token。

返回值

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

所属接口类

• AgoraMusicContentCenter

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:));

详情

自从

v4.1.0

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

参数

keyword

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

page

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

pageSize

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

jsonOption

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

Key 值	Value 值	示例
pitchType	是否支持打分： 1：支持打分的音乐资源。 2：不支持打分的音乐资源。	{"pitchType":1}
needHighPart	是否需要副歌片段资源： YES：需要副歌片段资源。 NO：不需要副歌片段资源。	{"needHighPart":true}

返回值

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

所属接口类

• AgoraMusicContentCenter

setPlayMode:

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

Objective-C

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

自从

v4.4.0

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

注意

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

适用场景

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

调用时机

该方法需要在 createMusicPlayerWithDelegate: 之后调用。

调用限制

无。

参数

mode

播放模式，详见 AgoraMusicPlayMode。

返回值

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

所属接口类

• AgoraMusicPlayerProtocol

onLyricResult:songCode:lyricUrl:reason:

歌词下载地址回调。

Objective-C

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

详情

自从

v4.1.0

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

参数

requestId

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

songCode

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

lyricUrl

歌词的下载地址。

reason

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

所属接口类

• AgoraMusicContentCenterEventDelegate

onMusicChartsResult:result:reason:

获取音乐榜单回调。

Objective-C

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

详情

自从

v4.1.0

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

参数

requestId

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

reason

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

result

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

所属接口类

• AgoraMusicContentCenterEventDelegate

onMusicCollectionResult:result:reason:

获取音乐资源列表回调。

Objective-C

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

详情

自从

v4.1.0

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

参数

requestId

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

reason

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

result

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

所属接口类

• AgoraMusicContentCenterEventDelegate

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;

详情

自从

v4.1.0

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

参数

requestId

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

songCode

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

percent

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

lyricUrl

歌词下载地址。

state

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

reason

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

所属接口类

• AgoraMusicContentCenterEventDelegate

onSongSimpleInfoResult:songCode:simpleInfo:reason:

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

Objective-C

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

详情

自从

v4.2.2

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

参数

requestId

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

songCode

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

simpleInfo

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

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

reason

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

所属接口类

• AgoraMusicContentCenterEventDelegate

openMediaWithSongCode:startPos:

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

Objective-C

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

详情

自从

v4.1.0

信息

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

在调用此方法之前，请确保需要播放的音乐资源已加载完成。你可以调用 isPreloadedWithSongCode: 方法来检测音乐资源是否已被预加载，或通过 onPreLoadEvent:songCode:percent:lyricUrl:state:reason: 回调得知。

调用该方法后会触发 AgoraRtcMediaPlayer:didChangedToState:reason: 回调。在收到报告播放状态为 AgoraMediaPlayerStateOpenCompleted 后，你可以调用 play 方法播放媒体文件。

参数

songCode

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

startPos

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

返回值

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

所属接口类

• AgoraMusicPlayerProtocol