版权音乐
介绍版权音乐的相关方法和回调。
sharedContentCenterWithConfig
+ (instancetype)sharedContentCenterWithConfig:(AgoraMusicContentCenterConfig *)config NS_SWIFT_NAME(sharedContentCenter(config:));
- 自从
- v4.1.0
在调用 AgoraMusicContentCenter 类下的其他方法前,你需要先调用该方法初始化 AgoraMusicContentCenter。
参数
- config
- AgoraMusicContentCenter 的设置,详见 AgoraMusicContentCenterConfig。
返回值
- 方法调用成功,返回一个 AgoraMusicContentCenter 实例。
- 方法调用失败,返回 nil。
destroy
registerEventDelegate
注册音乐内容中心回调事件。
- (NSInteger)registerEventDelegate:(id<AgoraMusicContentCenterEventDelegate> _Nullable)eventDelegate;
- 自从
- v4.1.0
参数
- eventDelegate
- 待注册的回调事件,详见 AgoraMusicContentCenterEventDelegate。如果你想移除已注册的回调事件,请传入 nil。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
createMusicPlayerWithDelegate
创建音乐播放器。
- (id<AgoraMusicPlayerProtocol>)createMusicPlayerWithDelegate:(id<AgoraRtcMediaPlayerDelegate>_Nullable)delegate NS_SWIFT_NAME(createMusicPlayer(delegate:));
- 自从
- v4.1.0
参数
- delegate
- 详见 AgoraRtcMediaPlayerDelegate。
返回值
- 方法调用成功:返回 AgoraMusicPlayerProtocol 实例。
- 方法调用失败:返回空指针。
enableMainQueueDispatch
是否分发回调至主队列。
- (void)enableMainQueueDispatch:(BOOL)enabled;
- 自从
- v4.1.0
如果不分发回调方法到主队列,app 应将 UI 操作分发到主队列。
参数
- enabled
-
YES
:分发回调方法到主队列。NO
:(默认)不分发回调方法到主队列。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getLyricWithSongCode
获取音乐资源的歌词下载地址。
- (NSString *)getLyricWithSongCode:(NSInteger)songCode lyricType:(NSInteger)lyricType NS_SWIFT_NAME(getLyric(songCode:lyricType:));
- 自从
- v4.1.0
成功调用该方法后,SDK 会触发 onLyricResult 回调报告歌词的下载地址。
参数
- songCode
- 音乐资源的编号,用于标识一个音乐资源。
- LyricType
- 歌词类型:
- 0:xml 格式。
- 1:lrc 格式。
返回值
一个 requestId,为本次请求的唯一标识。
getMusicCharts
获取全部音乐榜单。
- (NSString *)getMusicCharts;
- 自从
- v4.1.0
当你调用该方法后,SDK 会触发 onMusicChartsResult 回调报告音乐榜单的详细信息。
返回值
一个 requestId,为本次请求的唯一标识。
getMusicCollectionWithMusicChartId
通过音乐榜单的 ID 获取指定榜单的音乐资源列表。
- (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 回调报告榜单中音乐资源列表的详细信息。
参数
- musicChartId
- 音乐榜单的 ID,可以通过 onMusicChartsResult 回调获取。你也可以通过 RESTful API 来获取曲库所有歌曲列表或获取增量歌曲列表。
- page
- 当前页面编号,默认从 1 开始。
- pageSize
- 当前音乐资源列表的总页面数量,最大值为 50。
- jsonOption
- 扩展 JSON 字段,默认为 nil。
返回值
一个 requestId,为本次请求的唯一标识。
preloadWithSongCode
预加载音乐资源。
- (NSInteger)preloadWithSongCode:(NSInteger)songCode jsonOption:(NSString* _Nullable)jsonOption NS_SWIFT_NAME(preload(songCode:jsonOption:));
- 自从
- v4.1.0
你可以调用该方法预先加载需要播放的音乐资源。成功调用该方法后,SDK 会触发 onPreLoadEvent 回调报告预加载音乐资源的事件。
在调用该方法来预加载音乐资源之前,你需要调用 getMusicCollectionWithMusicChartId 或 searchMusicWithKeyWord 方法来获取你需要播放的音乐资源,并通过由此触发的 onMusicCollectionResult 回调获取音乐资源的编号(songCode)。
参数
- songCode
- 音乐资源的编号,用于标识一个音乐资源。
- jsonOption
-
扩展 JSON 字段。
Agora 会根据你在场景字段(sceneType)传入的应用场景进行收费。不同的应用场景对应不同的费率,你可以参考 计费说明 查看详细的计费。
- 1:直播场景:K 歌及背景音乐播放。
- 2:直播场景:背景音乐播放。
- 3:(默认)语聊场景:K 歌。
- 4:语聊场景:背景音乐播放。
- 5:VR 场景:K 歌及背景音乐播放。
示例:
{"sceneType":1}
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
isPreloadedWithSongCode
检测音乐资源是否已被预加载。
- (NSInteger)isPreloadedWithSongCode:(NSInteger)songCode NS_SWIFT_NAME(isPreloaded(songCode:));
- 自从
- v4.1.0
该方法为同步调用。如需预加载新的音乐资源,可调用 preloadWithSongCode。
参数
- songCode
- 音乐资源的编号,用于标识一个音乐资源。
返回值
- 0: 方法调用成功,该音乐资源已被预加载。
- < 0: 方法调用失败。
renewToken
更新 Token。
- (NSInteger)renewToken:(NSString * _Nonnull)token;
- 自从
- v4.1.0
当你用于鉴权的 Token 快要过期或已过期时,你可以调用该方法来传入新生成的 Token。
参数
- token
- 新的 Token。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
searchMusicWithKeyWord
搜索音乐资源。
- (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 回调报告检索到的音乐资源列表。
参数
- keyword
- 搜索关键词,支持歌曲名、歌手搜索。
- page
- 想要获取的音乐资源列表的目标页编号。
- pageSize
- 每页所展示的音乐资源的最大数量,最大值为 50。
- jsonOption
- 扩展 JSON 字段,默认为 nil。
返回值
一个 requestId,为本次请求的唯一标识。
openMediaWithSongCode
打开音乐内容中心的音乐资源。
- (NSInteger)openMediaWithSongCode:(NSInteger)songCode startPos:(NSInteger)startPos NS_SWIFT_NAME(openMedia(songCode:startPos:));
- 自从
- v4.1.0
在调用此方法之前,请确保需要播放的音乐资源已加载完成。你可以调用 isPreloadedWithSongCode 方法来检测音乐资源是否已被预加载,或通过 onPreLoadEvent 回调得知。
如需播放媒体文件,请在收到 didChangedToState 回调报告播放状态为 AgoraMediaPlayerStateOpenCompleted 后再调用 play 方法播放媒体文件。
参数
- songCode
- 音乐资源的编号,用于标识一个音乐资源。
- startPos
- 设置起始播放位置(毫秒),默认值为 0。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
onPreLoadEvent
报告预加载音乐资源的事件。
- (void)onPreLoadEvent:(NSInteger)songCode percent:(NSInteger)percent status:(AgoraMusicContentCenterPreloadStatus)status msg:(NSString *)msg lyricUrl:(NSString *)lyricUrl;
- 自从
- v4.1.0
当你调用 preloadWithSongCode 方法预加载音乐资源后,SDK 会触发该回调。
参数
- songCode
- 音乐资源的编号,用于标识一个音乐资源。
- percent
- 音乐资源当前的加载进度,取值范围为 [0,100]。
- lyricUrl
- 歌词下载地址。
- status
-
当前音乐资源的加载状态。详见 AgoraMusicContentCenterPreloadStatus。
- msg
- 加载状态信息。
onLyricResult
歌词下载地址回调。
- (void)onLyricResult:(NSString*)requestId lyricUrl:(NSString*)lyricUrl;
- 自从
- v4.1.0
当你调用 getLyricWithSongCode 获取指定歌曲的歌词下载地址后,SDK 会触发该回调。
参数
- requestId
- 请求 ID。本次请求的唯一标识。
- lyricUrl
- 歌词的下载地址。
onMusicChartsResult
获取音乐榜单回调。
- (void)onMusicChartsResult:(NSString *)requestId status:(AgoraMusicContentCenterStatusCode)status result:(NSArray<AgoraMusicChartInfo*> *)result;
- 自从
- v4.1.0
当你调用 getMusicCharts 方法获取全部音乐榜单之后,SDK 会触发该回调。
参数
- requestId
- 请求 ID。本次请求的唯一标识。
- status
请求状态,详见 AgoraMusicContentCenterStatusCode。
- result
- 当前可播放的音乐榜单列表。详见 AgoraMusicChartInfo。
onMusicCollectionResult
获取音乐资源列表回调。
- (void)onMusicCollectionResult:(NSString *)requestId status:(AgoraMusicContentCenterStatusCode)status result:(AgoraMusicCollection *)result;
- 自从
- v4.1.0
当你调 getMusicCollectionWithMusicChartId 方法来获取指定榜单的音乐资源列表,SDK 会触发此回调报告榜单中音乐资源列表的详细信息。
参数
- requestId
- 请求 ID。本次请求的唯一标识。
- status
请求状态,详见 AgoraMusicContentCenterStatusCode。
- result
- 音乐资源列表的详细信息。详见 AgoraMusicCollection。