获取版权音乐

声网内容中心提供 K 歌热门曲库，涵盖大量正版歌曲、歌词等。本文分别介绍如何使用实时互动 SDK API 及 RESTful API 获取并加载声网内容中心提供的版权音乐。

前提条件Copy Anchor Link

• 已实现基本的在线 K 歌逻辑，详情请参考快速集成 PaaS 方案。

• 已联系技术支持开通版权音乐权限。

• 有效的声网项目，详情请参考开通 PaaS 方案服务。

• 你的项目的 RTM Token。如何部署请参考部署 Token 服务器。

  信息

  RTM Token 仅用于内容中心鉴权，不会产生云信令服务费用。

实现流程Copy Anchor Link

本节介绍如何获取、加载版权音乐。

1. 初始设置Copy Anchor Link

1. 注册曲库并获取 IAgoraMusicContentCenter。

   Copy Text

   mcc = IAgoraMusicContentCenter.create(rtcEngine());

2. 初始化 IAgoraMusicContentCenter。

   Copy Text

   MusicContentCenterConfiguration contentCenterConfiguration = new MusicContentCenterConfiguration();
   //  已开启音乐内容中心项目的 App ID
   contentCenterConfiguration.appId = "填入你的 App ID";
   // 使用音乐内容中心的用户 ID。该 ID 可以和你加入 RTC 频道时使用的 uid 一致，但不能为 0
   contentCenterConfiguration.mccUid = 填入当前使用音乐内容中心用户的 uid;
   // 填入用于鉴权的 Token
   contentCenterConfiguration.token = "xxxxxxxxxxxx";
   // 创建 IAgoraMusicContentCenterEventHandler，用于 SDK 向客户端发送音乐内容中心事件通知
   contentCenterConfiguration.eventHandler = new IMusicContentCenterEventHandler(){};
   // 初始化 IAgoraMusicContentCenter
   mcc.initialize(contentCenterConfiguration);

3. 创建音乐播放器。如果你需要播放音乐内容中心的音乐资源，需要使用此播放器进行播放。

   Copy Text

   musicPlayer = mcc.createMusicPlayer();

2. 获取版权音乐Copy Anchor Link

针对 PaaS 方案，声网提供两种方式获取版权音乐：使用实时互动 SDK API 或 RESTful API 获取。

使用实时互动 APICopy Anchor Link

你可以通过以下 API 来获取音乐资源：

• getMusicCharts：获取曲库中全部的音乐榜单。
• getMusicCollectionByMusicChartId：通过音乐榜单的 ID 获取指定榜单的音乐资源列表。
• searchMusic ：通过关键词搜索并获取音乐资源。

mcc.getMusicCharts();
mcc.getMusicCollectionByMusicChartId(0,0,10);
mcc.searchMusic("hello",0,10);

你还可以通过 searchMusic[2/2] 和 getMusicCollectionByMusicChartId[2/2] 中的 jsonOption 字段来筛选有副歌片段、支持打分的音乐资源。jsonOption 字段的具体说明见对应方法的 API 文档。

筛选支持打分的音乐资源：

mMcc.searchMusic("千里之外", 1, 50, "{\"pitchType\":1}");
mMcc.getMusicCollectionByMusicChartId(3, 1, 10, "{\"pitchType\":1}");

筛选有副歌片段的音乐资源：

mMcc.searchMusic("千里之外", 1, 50, "{\"needHighPart\":true}");
mMcc.getMusicCollectionByMusicChartId(3, 1, 10, "{\"needHighPart\":true}");

使用 RESTful API 获取Copy Anchor Link

参考下列步骤来使用 RESTful API 从声网内容中心获取版权音乐。

1. 实现 HTTP 认证

   RESTful API 仅支持 HTTPS 协议。发送请求时，你需要通过 Basic HTTP 认证，并将生成的凭证填入 HTTP 请求头部的 Authorization 字段。具体生成 Authorization 字段的方法请参考 HTTP 基本认证。

2. 获取歌曲列表

   根据你的需求调用不同的 RESTful API 来获取歌曲列表、热门榜单等。调用说明及示例详见 API 文档。

3. 加载版权音乐Copy Anchor Link

本节介绍如何加载并打开版权音乐。

1. 预加载音乐资源。

   调用 preload 方法来预加载需要播放的音乐资源。加载音乐资源之后，你可以调用 isPreloaded 方法来检测音乐资源是否已被预加载，该方法可同步调用且不包含耗时操作。

   信息

   在播放音乐资源之前，请确保你已收到 onPreLoadEvent 回调报告音乐资源加载完成。

   Copy Text

   mcc.preload(songCode, null);
   mcc.isPreloaded(songCode);

   如果你需要预加载的是某一音乐资源独立的副歌片段，在预加载之前你还需要调用 getInternalSongCode 来获取该片段的资源编号（internalSongCode）。

   Copy Text

   // 传入音乐资源的编号和 jsonOption 的值来获取副歌片段的资源编号，详细参数解释请参考该方法的 API 文档
   mMcc.getInternalSongCode(songCode, "{\"format\":{\"highpart\":0}}");
   // 将获取到的副歌片段资源编号传入 songCode 参数来预加载该片段
   int ret = mMcc.preload(songCode);

   注意

   在调用相应方法打开、移除副歌片段时，请将该片段的资源编号传入相应方法中的 songCode 参数。

2. 打开音乐资源。

   调用 open 方法打开音乐资源。

   Copy Text

   musicPlayer.open(songCode, 0);

   注意

   调用 open 后，请确保收到 onPlayerStateChanged 回调报告状态为 PLAYER_STATE_OPEN_COMPLETED(2) 再调用 play 来进行播放。

获取版权音乐后，你可以参考实现文档实现其他 K 歌功能。

API 参考Copy Anchor Link

本节介绍获取版权音乐使用的 API：

• 实时互动 SDK API
• RESTful API

相关文档Copy Anchor Link

本节介绍 PaaS 方案的相关实现文档：

• 快速集成 PaaS 方案
• 歌词打分组件
• 歌词强同步

声网内容中心提供 K 歌热门曲库，涵盖大量正版歌曲、歌词等。本文分别介绍如何使用实时互动 SDK API 及 RESTful API 获取并加载声网内容中心提供的版权音乐。

前提条件Copy Anchor Link

• 已实现基本的在线 K 歌逻辑，详情请参考快速集成 PaaS 方案。

• 已联系技术支持开通版权音乐权限。

• 有效的声网项目，详情请参考开通 PaaS 方案服务。

• 你的项目的 RTM Token。如何部署请参考部署 Token 服务器。

  信息

  RTM Token 仅用于内容中心鉴权，不会产生云信令服务费用。

实现流程Copy Anchor Link

本节介绍如何获取、加载版权音乐。

1. 初始设置Copy Anchor Link

1. 注册曲库并初始化 AgoraMusicContentCenter。

AgoraMusicContentCenterConfig *config = [AgoraMusicContentCenterConfig new];
// 填入已开启音乐内容中心项目的 App ID
config.appId = xxx
// 用户 ID，该 ID 可以和你加入 RTC 频道时使用的 uid 一致，但不能为 0
config.mccUid = xxx
// 填入用于鉴权的 Token
config.token = xxx
// AgoraRtcEngineKit 实例
config.rtcEngine = xxx
AgoraMusicContentCenter *amcc = [AgoraMusicContentCenter sharedContentCenterWithConfig:config];

let config = AgoraMusicContentCenterConfig()
// 填入已开启音乐内容中心项目的 App ID
config.appId = xxx
// 用户 ID，该 ID 可以和你加入 RTC 频道时使用的 uid 一致，但不能为 0
config.mccUid = xxx
// 填入用于鉴权的 Token
config.token = xxx
// AgoraRtcEngineKit 实例
config.rtcEngine = xxx
amcc = AgoraMusicContentCenter.sharedContentCenter(with: config)

2. 创建音乐播放器。如果你需要播放音乐内容中心的音乐资源，需要使用此播放器进行播放。

id<AgoraMusicPlayerProtocol> musicPlayer = [amcc createMusicPlayerWithDelegate:self];

musicPlayer = amcc.createMusicPlayer(with:sdkEvent as! AgoraRtcMediaPlayerDelegate)

2. 获取版权音乐Copy Anchor Link

针对 PaaS 方案，声网提供两种方式获取版权音乐：使用实时互动 SDK API 或 RESTful API 获取。

使用实时互动 APICopy Anchor Link

你可以通过以下 API 来获取音乐资源：

• getMusicCharts：获取曲库中全部的音乐榜单。
• getMusicCollectionWithMusicChartId：通过音乐榜单的 ID 获取指定榜单的音乐资源列表。
• searchMusicWithKeyWord：通过关键词搜索并获取音乐资源。

[amcc getMusicCharts];
[amcc getMusicCollectionWithMusicChartId:musicChartId page:page pageSize:pageSize jsonOption: jsonOption];
[amcc searchMusicWithKeyWord:keyword page:page pageSize:pageSize jsonOption:nil];

amcc.getMusicCharts()
amcc.getMusicCollection(musicChartId: musicChartId, page: page, pageSize: pageSize, jsonOption: jsonOption)
amcc.searchMusic(with:keyword, page:page, pageSize:pageSize, jsonOption:jsonOption)

你还可以通过 searchMusicWithKeyWord 和 getMusicCollectionWithMusicChartId 中的 jsonOption 字段来筛选有副歌片段、支持打分的音乐资源。jsonOption 字段的具体说明见对应方法的 API 文档。

筛选支持打分的音乐资源：

//筛选支持打分的音乐资源：
[self.mcc searchMusicWithKeyWord:@"千里之外" page:1 pageSize:50 jsonOption:@"{\"pitchType\":1}"];
[self.mcc getMusicCollectionWithMusicChartId:3 page:1 pageSize:50 jsonOption:@"{\"pitchType\":1}"];

amcc.searchMusic(keyWord: "千里之外", page: 1, pageSize: 50, jsonOption: "{\"pitchType\":1}")
amcc.getMusicCollection(musicChartId: 3, page: 1, pageSize: 10, jsonOption: "{\"pitchType\":1}")

筛选有副歌片段的音乐资源：

//筛选有副歌片段的音乐资源：
[self.mcc searchMusicWithKeyWord:@"千里之外" page:1 pageSize:50 jsonOption:@"{\"needHighPart\":true}"];
[self.mcc getMusicCollectionWithMusicChartId:3 page:1 pageSize:50 jsonOption:@"{\"needHighPart\":true}"];

amcc.searchMusic(keyWord: "千里之外", page: 1, pageSize: 50, jsonOption: "{\"needHighPart\":true}")
amcc.getMusicCollection(musicChartId: 3, page: 1, pageSize: 10, jsonOption: "{\"needHighPart\":true}")

使用 RESTful API 获取Copy Anchor Link

参考下列步骤来使用 RESTful API 从声网内容中心获取版权音乐。

1. 实现 HTTP 认证

   RESTful API 仅支持 HTTPS 协议。发送请求时，你需要通过 Basic HTTP 认证，并将生成的凭证填入 HTTP 请求头部的 Authorization 字段。具体生成 Authorization 字段的方法请参考 HTTP 基本认证。

2. 获取歌曲列表

   根据你的需求调用不同的 RESTful API 来获取歌曲列表、热门榜单等。调用说明及示例详见 API 文档。

3. 加载版权音乐Copy Anchor Link

本节介绍如何加载并打开版权音乐。

1. 预加载音乐资源。

   调用 preloadWithSongCode 方法来预加载需要播放的音乐资源。你可以调用 isPreloadedWithSongCode 方法来检测音乐资源是否已被预加载，该方法可同步调用且不包含耗时操作。

   注意

   在播放音乐资源之前，请确保你已收到 onPreLoadEvent 回调报告音乐资源加载完成。

[amcc preloadWithSongCode:songCode jsonOption:nil];
[amcc isPreloadedWithSongCode:songCode];

amcc.preload(songCode: songCode, jsonOption: nil)
amcc.isPreloaded(songCode: songCode)

如果你需要预加载的是某一音乐资源独立的副歌片段，在预加载之前你还需要调用 getInternalSongCode 来获取该片段的资源编号（internalSongCode）。

NSInteger newSongCode = [self.mcc getInternalSongCode:songCode jsonOption:@"{\"format\":{\"highpart\":0}}"];
[self.mcc preloadWithSongCode:newSongCode];

// 传入音乐资源的编号和 jsonOption 的值来获取副歌片段的资源编号，详细参数解释请参考该方法的 API 文档
songCode = amcc.getInternalSongCode(songCode: songCode, jsonOption: "{\"format\":{\"highpart\":0}}")
// 将获取到的副歌片段资源编号传入 songCode 参数来预加载该片段
let requestId = amcc.preload(songCode: songCode)

2. 打开音乐资源。

   调用 openMediaWithSongCode 方法打开音乐资源。

[musicPlayer openMediaWithSongCode:songCode startPos:0];

mPlayer.openMedia(withSongCode: songCode, startPos: startPos)

获取版权音乐后，你可以参考实现文档实现其他 K 歌功能。

API 参考Copy Anchor Link

本节介绍获取版权音乐使用的 API：

• 实时互动 SDK API
• RESTful API

相关文档Copy Anchor Link

本节介绍 PaaS 方案的相关实现文档：

• 快速集成 PaaS 方案
• 歌词打分组件
• 歌词强同步