版权音乐

createMusicPlayerWithDelegate:

创建一个音乐播放器。

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

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

参数

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

返回值

方法调用成功，返回 AgoraMusicPlayerProtocol 对象。
方法调用失败，返回 nil。

所属接口类

AgoraMusicContentCenter

destroy

销毁 AgoraMusicContentCenter 实例。

Objective-C
+ (void)destroy;

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

所属接口类

AgoraMusicContentCenter

destroyMusicPlayer:

销毁音乐播放器对象。

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

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

调用时机

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

参数

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

返回值

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

所属接口类

AgoraMusicContentCenter

enableMainQueueDispatch:

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

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

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

参数

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

所属接口类

AgoraMusicContentCenter

getCaches

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

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

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

返回值

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

所属接口类

AgoraMusicContentCenter

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：方法调用失败。详见错误码了解详情和解决建议。详见错误码文档获取详细信息和排查建议。

所属接口类

AgoraMusicContentCenter

getLyricWithSongCode:lyricType:

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

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

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

参数

songCode

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

lyricType

歌词的类型：

0：XML 格式。
1：LRC 格式。

返回值

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

所属接口类

AgoraMusicContentCenter

getMusicCharts

获取所有音乐排行榜。

Objective-C
- (NSString *)getMusicCharts;

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

返回值

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

所属接口类

AgoraMusicContentCenter

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

参数

musicChartId

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

page

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

pageSize

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

jsonOption

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

pitchType：是否支持评分。
- 1：支持评分的音乐资源。
- 2：不支持评分的音乐资源。
needHighPart：是否需要副歌片段资源。
- true：需要副歌片段资源。
- false：不需要副歌片段资源。

返回值

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

所属接口类

AgoraMusicContentCenter

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。

所属接口类

AgoraMusicContentCenter

sharedContentCenterWithConfig:

初始化 AgoraMusicContentCenter。

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

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

参数

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

返回值

方法调用成功时，返回一个 AgoraMusicContentCenter 对象。
方法调用失败时，返回 nil。

所属接口类

AgoraMusicContentCenter

isPreloadedWithSongCode:

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

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

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

参数

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

返回值

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

所属接口类

AgoraMusicContentCenter

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：方法调用失败。详见错误码了解详情和解决建议。详见错误码及对应的解决方案。

所属接口类

AgoraMusicPlayerProtocol

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 方法。

参数

songCode

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

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

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

信息

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

参数

songCode: 音乐资源的标识符。

返回值

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

所属接口类

AgoraMusicContentCenter

registerEventDelegate:

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

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

参数

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

返回值

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

所属接口类

AgoraMusicContentCenter

removeCacheWithSongCode:

删除已缓存的音乐资源。

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

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

信息

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

参数

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

返回值

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

所属接口类

AgoraMusicContentCenter

renewToken:

更新用于鉴权的 Token。

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

当用于鉴权的 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:));

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

参数

keyWord

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

page

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

pageSize

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

jsonOption

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

pitchType：音乐资源是否支持评分。
- 1：可评分的音乐资源。
- 2：不可评分的音乐资源。

示例：{"pitchType":1}。

needHighPart：是否需要合唱片段资源。
- YES：需要合唱片段资源。
- NO：不需要合唱片段资源。

示例：{"needHighPart":true}。

返回值

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

所属接口类

AgoraMusicContentCenter

setPlayMode:

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

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

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

信息

你可以通过 onMusicCollectionResult 回调获取音乐资源的详细信息。从 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;

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

触发时机

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

参数

requestId: 请求 ID，用于唯一标识该请求。
songCode: 音乐资源的标识符，用于指定音乐资源。
lyricUrl: 歌词的下载链接。
reason: 请求状态码，详见 AgoraMusicContentCenterStateReason。

所属接口类

AgoraMusicContentCenterEventDelegate

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。

所属接口类

AgoraMusicContentCenterEventDelegate

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。

所属接口类

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;

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

触发时机

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

参数

requestId: 请求 ID，用于唯一标识该请求。
songCode: 音乐资源的编号，用于标识特定的音乐资源。
percent: 音乐资源当前的加载进度，取值范围为 [0, 100]。
lyricUrl: 歌词的下载地址。
state: 音乐资源当前的加载状态，详见 AgoraMusicContentCenterPreloadState。
reason: 来自音乐内容中心的请求状态码，详见 AgoraMusicContentCenterStateReason。

所属接口类

AgoraMusicContentCenterEventDelegate

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。

所属接口类

AgoraMusicContentCenterEventDelegate

createMusicPlayerWithDelegate:

参数​

返回值​

destroy

destroyMusicPlayer:

调用时机

参数​

返回值​

enableMainQueueDispatch:

参数​

getCaches

返回值​

getInternalSongCode:jsonOption:

参数​

返回值​

getLyricWithSongCode:lyricType:

相关回调

参数​

返回值​

getMusicCharts

相关回调

返回值​

getMusicCollectionWithMusicChartId:page:pageSize:jsonOption:

相关回调

参数​

返回值​

getSongSimpleInfoWithSongCode:

参数​

返回值​

sharedContentCenterWithConfig:

参数​

返回值​

isPreloadedWithSongCode:

参数​

返回值​

openMediaWithSongCode:startPos:

参数​

返回值​

preloadWithSongCode:jsonOption:

相关回调

参数​

返回值​

preloadWithSongCode:

相关回调

参数​

返回值​

registerEventDelegate:

参数​

返回值​

removeCacheWithSongCode:

参数​

返回值​

renewToken:

参数​

返回值​

searchMusicWithKeyWord:page:pageSize:jsonOption:

参数​

返回值​

setPlayMode:

适用场景

调用时机

参数​

返回值​

onLyricResult:songCode:lyricUrl:reason:

触发时机

参数​

onMusicChartsResult:result:reason:

触发时机

参数​

onMusicCollectionResult:result:reason:

触发时机

参数​

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

触发时机

参数​

onSongSimpleInfoResult:songCode:simpleInfo:reason:

触发时机

参数​

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

返回值

参数

参数

参数

参数

参数