# 获取版权音乐 (/zh-CN/solutions/online-ktv/online-ktv-sdk/build/extend-karaoke/get-music)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

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

## 前提条件 [#前提条件]

- 已实现基本的在线 K 歌逻辑，详情请参考[快速集成 PaaS 方案](/zh-CN/solutions/online-ktv/online-ktv-sdk/get-started/karaoke)。
- 已联系[技术支持](https://ticket.shengwang.cn)开通版权音乐权限。
- 有效的声网项目，详情请参考[开通 PaaS 方案服务](/zh-CN/solutions/online-ktv/online-ktv-sdk/build/setup-and-access/enable-service)。
- 你的项目的 RTM Token。如何部署请参考[部署 Token 服务器](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation)。

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

## 实现流程 [#实现流程]

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

### 1. 初始设置 [#1-初始设置]

1. 注册曲库并获取 `IAgoraMusicContentCenter`。

   ```java
   mcc = IAgoraMusicContentCenter.create(rtcEngine());
   ```

2. 初始化 `IAgoraMusicContentCenter`。

   ```java
   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. 创建音乐播放器。如果你需要播放音乐内容中心的音乐资源，需要使用此播放器进行播放。

   ```java
   musicPlayer = mcc.createMusicPlayer();
   ```

<a id="步骤2"></a>
### 2. 获取版权音乐 [#2-获取版权音乐]

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

#### 使用实时互动 API [#使用实时互动-api]

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

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

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

你还可以通过 [searchMusic[2/2]](/zh-CN/api-reference/rtc/android/play/drm#searchmusic-22) 和 [getMusicCollectionByMusicChartId[2/2]](/zh-CN/api-reference/rtc/android/play/drm#getmusiccollectionbymusicchartid-22) 中的 `jsonOption` 字段来筛选有副歌片段、支持打分的音乐资源。`jsonOption` 字段的具体说明见对应方法的 API 文档。

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

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

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

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

#### 使用 RESTful API 获取 [#使用-restful-api-获取]

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

1. 实现 HTTP 认证

   RESTful API 仅支持 HTTPS 协议。发送请求时，你需要通过 Basic HTTP 认证，并将生成的凭证填入 HTTP 请求头部的 `Authorization` 字段。具体生成 `Authorization` 字段的方法请参考[ HTTP 基本认证](/zh-CN/realtime-media/rtc/build/setup-and-access/http-basic-auth)。

2. 获取歌曲列表

   根据你的需求调用不同的 RESTful API 来获取歌曲列表、热门榜单等。调用说明及示例详见 [API 文档](/zh-CN/api-reference/online-ktv)。

### 3. 加载版权音乐 [#3-加载版权音乐]

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

1. 预加载音乐资源。

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

   :::info[信息]
   在播放音乐资源之前，请确保你已收到 `onPreLoadEvent` 回调报告音乐资源加载完成。
   :::

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

   如果你需要预加载的是某一音乐资源独立的副歌片段，在预加载之前你还需要调用 [getInternalSongCode](/zh-CN/api-reference/rtc/android/play/drm#getinternalsongcode) 来获取该片段的资源编号（`internalSongCode`）。

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

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

2. 打开音乐资源。

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

   ```java
   musicPlayer.open(songCode, 0);
   ```

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

获取版权音乐后，你可以参考[实现文档](/zh-CN/solutions/online-ktv/online-ktv-sdk/get-started/karaoke)实现其他 K 歌功能。

## API 参考 [#api-参考]

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

- [实时互动 SDK API](/zh-CN/api-reference/online-ktv)
- [RESTful API](/zh-CN/api-reference/online-ktv)

## 相关文档 [#相关文档]

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

- [快速集成 PaaS 方案](/zh-CN/solutions/online-ktv/online-ktv-sdk/get-started/karaoke)
- [歌词打分组件](/zh-CN/api-reference/online-ktv)
- [歌词强同步](/zh-CN/solutions/online-ktv/online-ktv-sdk/build/extend-karaoke/lyrics-syncing)
<_PlatformProcessedMarker close="true" />

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

## 前提条件 [#前提条件-1]

- 已实现基本的在线 K 歌逻辑，详情请参考[快速集成 PaaS 方案](/zh-CN/solutions/online-ktv/online-ktv-sdk/get-started/karaoke)。
- 已联系[技术支持](https://ticket.shengwang.cn)开通版权音乐权限。
- 有效的声网项目，详情请参考[开通 PaaS 方案服务](/zh-CN/solutions/online-ktv/online-ktv-sdk/build/setup-and-access/enable-service)。
- 你的项目的 RTM Token。如何部署请参考[部署 Token 服务器](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation)。

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

## 实现流程 [#实现流程-1]

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

### 1. 初始设置 [#1-初始设置-1]

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

```objc tab="Objective-C" tabGroup="player"
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];
```

```swift tab="Swift" tabGroup="player"
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. 创建音乐播放器。如果你需要播放音乐内容中心的音乐资源，需要使用此播放器进行播放。

```objc tab="Objective-C" tabGroup="create-player"
id<AgoraMusicPlayerProtocol> musicPlayer = [amcc createMusicPlayerWithDelegate:self];
```

```swift tab="Swift" tabGroup="create-player"
musicPlayer = amcc.createMusicPlayer(with:sdkEvent as! AgoraRtcMediaPlayerDelegate)
```

<a id="步骤2"></a>
### 2. 获取版权音乐 [#2-获取版权音乐-1]

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

#### 使用实时互动 API [#使用实时互动-api-1]

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

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

```objc tab="Objective-C" tabGroup="music"
[amcc getMusicCharts];
[amcc getMusicCollectionWithMusicChartId:musicChartId page:page pageSize:pageSize jsonOption: jsonOption];
[amcc searchMusicWithKeyWord:keyword page:page pageSize:pageSize jsonOption:nil];
```

```swift tab="Swift" tabGroup="music"
amcc.getMusicCharts()
amcc.getMusicCollection(musicChartId: musicChartId, page: page, pageSize: pageSize, jsonOption: jsonOption)
amcc.searchMusic(with:keyword, page:page, pageSize:pageSize, jsonOption:jsonOption)
```

你还可以通过 [searchMusicWithKeyWord](/zh-CN/api-reference/rtc/ios/play/drm) 和 [getMusicCollectionWithMusicChartId](/zh-CN/api-reference/rtc/ios/play/drm) 中的 `jsonOption` 字段来筛选有副歌片段、支持打分的音乐资源。`jsonOption` 字段的具体说明见对应方法的 API 文档。

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

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

```swift tab="Swift" tabGroup="score"
amcc.searchMusic(keyWord: "千里之外", page: 1, pageSize: 50, jsonOption: "{\"pitchType\":1}")
amcc.getMusicCollection(musicChartId: 3, page: 1, pageSize: 10, jsonOption: "{\"pitchType\":1}")
```

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

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

```swift tab="Swift" tabGroup="high-part"
amcc.searchMusic(keyWord: "千里之外", page: 1, pageSize: 50, jsonOption: "{\"needHighPart\":true}")
amcc.getMusicCollection(musicChartId: 3, page: 1, pageSize: 10, jsonOption: "{\"needHighPart\":true}")
```

#### 使用 RESTful API 获取 [#使用-restful-api-获取-1]

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

1. 实现 HTTP 认证

   RESTful API 仅支持 HTTPS 协议。发送请求时，你需要通过 Basic HTTP 认证，并将生成的凭证填入 HTTP 请求头部的 `Authorization` 字段。具体生成 `Authorization` 字段的方法请参考[ HTTP 基本认证](/zh-CN/realtime-media/rtc/build/setup-and-access/http-basic-auth)。

2. 获取歌曲列表

   根据你的需求调用不同的 RESTful API 来获取歌曲列表、热门榜单等。调用说明及示例详见 [API 文档](/zh-CN/api-reference/online-ktv)。

### 3. 加载版权音乐 [#3-加载版权音乐-1]

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

1. 预加载音乐资源。

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

   :::warning[注意]
   在播放音乐资源之前，请确保你已收到 `onPreLoadEvent` 回调报告音乐资源加载完成。
   :::

```objc tab="Objective-C" tabGroup="preload"
[amcc preloadWithSongCode:songCode jsonOption:nil];
[amcc isPreloadedWithSongCode:songCode];
```

```swift tab="Swift" tabGroup="preload"
amcc.preload(songCode: songCode, jsonOption: nil)
amcc.isPreloaded(songCode: songCode)
```

   如果你需要预加载的是某一音乐资源独立的副歌片段，在预加载之前你还需要调用 [getInternalSongCode](/zh-CN/api-reference/rtc/ios/play/drm#api_imusiccontentcenter_getinternalsongcode) 来获取该片段的资源编号（`internalSongCode`）。

```objc tab="Objective-C" tabGroup="internal"
NSInteger newSongCode = [self.mcc getInternalSongCode:songCode jsonOption:@"{\"format\":{\"highpart\":0}}"];
[self.mcc preloadWithSongCode:newSongCode];
```

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

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

2. 打开音乐资源。

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

```objc tab="Objective-C" tabGroup="open"
[musicPlayer openMediaWithSongCode:songCode startPos:0];
```

```swift tab="Swift" tabGroup="open"
mPlayer.openMedia(withSongCode: songCode, startPos: startPos)
```

   :::warning[注意]
   调用 `openMediaWithSongCode` 后，请确保收到 `didChangedToState` 回调报告状态为 `AgoraMediaPlayerStateOpenCompleted` 再调用 `play` 来进行播放。
   :::

获取版权音乐后，你可以参考[实现文档](/zh-CN/solutions/online-ktv/online-ktv-sdk/get-started/karaoke)实现其他 K 歌功能。

## API 参考 [#api-参考-1]

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

- [实时互动 SDK API](/zh-CN/api-reference/online-ktv)
- [RESTful API](/zh-CN/api-reference/online-ktv)

## 相关文档 [#相关文档-1]

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

- [快速集成 PaaS 方案](/zh-CN/solutions/online-ktv/online-ktv-sdk/get-started/karaoke)
- [歌词打分组件](/zh-CN/api-reference/online-ktv)
- [歌词强同步](/zh-CN/solutions/online-ktv/online-ktv-sdk/build/extend-karaoke/lyrics-syncing)
<_PlatformProcessedMarker close="true" />
</_PlatformTabsGroup>