获取版权音乐

声网内容中心提供 K 歌热门曲库，涵盖大量正版歌曲、歌词等。本文分别介绍如何使用 KTV 场景化 API 及 RESTful API 获取声网内容中心提供的版权音乐并进行播放。

前提条件

已实现基本的在线 K 歌逻辑，详情请参考快速集成 KTV API。
已联系技术支持开通版权音乐权限。
有效的声网项目，详情请参考开通场景化 API 方案服务。
如果你使用场景化 API 获取版权音乐，需要获取项目的 RTM Token。
信息
- 加载版权音乐时声网使用 RTM Token 进行鉴权，不会产生云信令服务费用。
- 你可以参考开通场景化 API 方案服务获取临时 RTM Token 用于测试，但在正式生产环境中，你需要自己部署一个 RTM Token 服务器来生成、更新 Token，详见部署 RTM Token。
如果你的网络环境部署了防火墙，请参考应用企业防火墙限制以正常使用声网服务。

实现流程

本节介绍如何获取版权歌单、加载并播放版权音乐。

1. 初始化设置

调用 createKTVApi 创建并初始化 KTV API 实例时，确保 KTVApiConfig 中的 musicType 设为 SONG_CODE（表示使用声网音乐内容中心提供的版权音乐）并填入 RTM Token 进行鉴权。

Kotlin

// 创建并初始化 KTVAPI 模块
val ktvApiProtocol =
    createKTVApi(
        KTVApiConfig(
            // 你的 App ID
            "<Your Agora Appid>",
            // RTM Token，如果你使用的是本地的曲库而非声网提供的版权音乐，该参数可为空
            "<Your Agora Rtm Token>",
            mRtcEngine,
            // 需加入的频道名称
            "<Your Channel Name>",
            // 用户 ID
            "<Your Uid>",
            // 合唱子频道的频道名，由外部指定
            "<Your Chorus Channel Name>",
            // 根据合唱子频道名和用户 ID 生成的 Token，用于加入该频道时鉴权
            "<Your Agora Chorus Token>"
        ),
        // 设置可缓存的音乐资源数量，最多不能超过 50
        10,
        // 设置 K 歌的场景
        KTVType.Normal,
        // 音乐资源类型，默认为声网音乐内容中心提供的版权音乐
        KTVMusicType.SONG_CODE
    )

信息

当用于音乐内容中心鉴权的 RTM Token 即将过期时，你会收到 onTokenPrivilegeWillExpire 回调。你需要调用 KTVApi 下的 renewToken 来更新 Token。

2. 获取版权音乐

针对场景化 API 方案，声网提供两种方式获取版权音乐：场景化 API 及 RESTful API。

使用场景化 API 获取

调用 searchMusicByKeyword 通过关键词搜索歌曲，也可以调用 fetchMusicCharts 获取音乐榜单，然后再调用 searchMusicByMusicChartId 通过歌曲榜单的 ID 获取指定榜单的歌曲资源列表。

Kotlin

// 用关键词搜索歌曲
fun searchSong(condition: String, page: Int) {
    val jsonOption = "{\"pitchType\":1,\"needLyric\":true}" // 搜索过滤条件。
    ktvApiProtocol.searchMusicByKeyword(condition, page, 50, jsonOption) {
        requestId,
        status,
        page,
        pageSize,
        total,
        list ->
        // 回调内直接处理异步调用结果
    }
}

Kotlin

// 获取音乐榜单
fun fetchMusicCharts() {
    ktvApiProtocol.fetchMusicCharts() { requestId, status, list ->
        // 回调内直接处理异步调用结果
    }
}

// 通过榜单号获取歌曲列表
fun searchSongWithRankingChartId(type: Int, page: Int) {
    val jsonOption = "{\"pitchType\":1,\"needLyric\":true}" // 过滤条件
    ktvApiProtocol.searchMusicByMusicChartId(type, page, 50, jsonOption) {
        requestId,
        status,
        page,
        pageSize,
        total,
        list ->
        // 回调内直接处理异步调用结果
    }
}

注意

你可以通过 jsonOption 字段来筛选有副歌片段、支持打分的音乐资源。jsonOption 字段的具体说明见 searchMusicByKeyword 及 searchMusicByMusicChartId 的 API 文档。

使用 RESTful API 获取

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

实现 HTTP 认证

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

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

3. 加载及播放版权音乐

成功获取版权音乐后，调用 loadMusic[1/2] 加载歌曲。该方法中你需要传入歌曲编号并进行歌曲加载配置。歌曲加载结果会通过 IMusicLoadStateListener 接口类下的回调通知你。在调用该方法时，你需要传入下列参数：

songCode：歌曲编号。如果你需要播放歌曲的副歌片段，需要先调用 getInternalSongCode 方法为该片段创建一个编号，作为该片段的唯一标识。当你获取到该片段的编号后，调用 loadMusic[1/2] 并将获取到的副歌片段编号传入 songCode 参数来加载该副歌片段。
config：歌曲加载配置，包含下列参数：
- songIdentifier：歌曲的唯一标识。如果你使用的是自行维护的曲库，你需要传入该参数，并需确保唯一性。如果你使用的是声网提供的版权音乐，向 songCode 传参即可，此参数传空。
- mode：歌曲加载的模式，默认为加载歌曲及歌词。
- mainSingerUid：独唱者的用户 ID。
IMusicLoadStateListener：监听歌曲加载状态的接口类。

信息

目前仅支持一次加载一首歌曲，请在一首歌曲加载完成后再加载下一首。

Kotlin

// 下列示例代码以独唱者为例，展示如何加载、播放版权音乐
// 歌曲加载成功后需要在 onMusicLoadSuccess 回调内调用 switchSingerRole 切换用户角色为独唱者，再调用 startSing 开始演唱
ktvApiProtocol.loadMusic(
    songCode,
    KTVLoadMusicConfiguration(songId, mainSingerUid, KTVLoadMusicMode.LOAD_MUSIC_AND_LRC),
    object : IMusicLoadStateListener {
        override fun onMusicLoadSuccess(songCode: Long, lyricUrl: String) {
            // 歌曲加载成功后，调用 switchSingerRole 将用户角色设为独唱者
            ktvApiProtocol.switchSingerRole(SoloSinger)
            // 开始唱歌
            ktvApiProtocol.startSing(songCode, 0)
        }
        // 加载失败
        override fun onMusicLoadFail(songCode: Long, reason: KTVLoadSongFailReason) {
        }
        // 报告加载进度
        override fun onMusicLoadProgress(
            songCode: Long,
            percent: Int,
            status: MusicLoadStatus,
            msg: String?,
            lyricUrl: String?
        ) {
        }
    }

如果你需要取消当前正在加载的版权音乐、或者清除已加载的缓存，可以调用 removeMusic 方法。

Kotlin

ktvApiProtocol.removeMusic(songCode)

API 参考

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

前提条件

已实现基本的在线 K 歌逻辑，详情请参考快速集成 KTV API。
已联系技术支持开通版权音乐权限。
有效的声网项目，详情请参考开通场景化 API 方案服务。
如果你使用场景化 API 获取版权音乐，需要获取项目的 RTM Token。
信息
- 加载版权音乐时声网使用 RTM Token 进行鉴权，不会产生云信令服务费用。
- 你可以参考开通场景化 API 方案服务获取临时 RTM Token 用于测试，但在正式生产环境中，你需要自己部署一个 RTM Token 服务器来生成、更新 Token，详见部署 RTM Token。
如果你的网络环境部署了防火墙，请参考应用企业防火墙限制以正常使用声网服务。

实现流程

本节介绍如何获取版权歌单、加载并播放版权音乐。

1. 初始化设置

调用 init 初始化 KTV API 实例时，确保 KTVApiConfig 中的 musicType 设为 loadMusicTypelocal（表示使用声网音乐内容中心提供的版权音乐）并填入 RTM Token 进行鉴权。

Objective-C

KTVApiConfig *apiConfig = [[KTVApiConfig alloc]initWithAppId:[[AppContext shared] appId]
                                                    // RTM Token，仅在使用声网版权音乐时需要填该参数
                                                    rtmToken:VLUserCenter.user.agoraRTMToken
                                                      engine:self.RTCkit
                                                 // 需加入的频道名称
                                                 channelName:@""
                                           // 合唱子频道的频道名，由外部指定
                                           chorusChannelName:@""
                                          // 根据合唱子频道名和用户 ID 生成的 Token，用于加入该频道时鉴权
                                          chorusChannelToken:@""
                                                        // 设置 K 歌的场景
                                                        type:KTVTypeNormal
                                                  // 设置可缓存的音乐资源数量，最多不能超过 50
                                                maxCacheSize:10
                                                   // 设置音乐资源类型为版权音乐
                                                   musicType:loadMusicTypelocal
                                                   // mcc域名
                                                   mccDomain:nil];
[self.ktvApi loadMusicWithConfig:config url:@"Your music url"];

信息

当用于音乐内容中心鉴权的 RTM Token 即将过期时，你会收到 onTokenPrivilegeWillExpire 回调。你需要调用 KTVApi 下的 renewToken 来更新 Token。

2. 获取版权音乐

针对场景化 API 方案，声网提供两种方式获取版权音乐：场景化 API 及 RESTful API。

使用场景化 API 获取

你可以调用 searchMusic[2/2] 来通过关键词搜索歌曲，也可以调用 fetchMusicCharts 来获取音乐榜单，然后再调用 searchMusic[1/2] 来通过歌曲榜单的 ID 获取指定榜单的歌曲资源列表。

Objective-C

// 通过关键词搜索歌曲
- (void)loadSearchDataWithKeyWord:(NSString *)keyWord {
    NSDictionary *dict = @{
        @"pitchType" : @(1),
        // 用来过滤没有歌词的歌曲
        @"needLyric" : @(YES),
    };
    NSString *extra = [NSString convertToJsonData:dict];
    [self.ktvApi searchMusicWithKeyword:keyWord ? keyWord : @""
                                   page:self.page
                               pageSize:50
                             jsonOption:extra
                             completion:^(NSString *_Nonnull, AgoraMusicContentCenterStatusCode,
                                          AgoraMusicCollection *_Nonnull){
                             }];
}

Objective-C

// 获取榜单之前先要获取榜单 ID
[self.ktvApi
    fetchMusicChartsWithCompletion:^(NSString *requestId, AgoraMusicContentCenterStatusCode code,
                                     NSArray<AgoraMusicChartInfo *> *info){
    }];

- (void)loadDataWithIndex:(NSInteger)pageType {
    NSArray *chartIds = @[ @(3), @(4), @(2), @(6) ];
    NSInteger chartId = [[chartIds objectAtIndex:MIN(pageType - 1, chartIds.count - 1)] intValue];
    NSDictionary *dict = @{
        @"pitchType" : @(1),
        //用来过滤没有歌词的歌曲
        @"needLyric" : @(YES),
    };
    NSString *extra = [NSString convertToJsonData:dict];
    // 根据榜单 ID 获取歌曲列表
    [self.ktvApi
        searchMusicWithMusicChartId:chartId
                               page:self.page
                           pageSize:20
                         jsonOption:extra
                         completion:^(NSString *_Nonnull, AgoraMusicContentCenterStatusCode,
                                      AgoraMusicCollection *_Nonnull){
                         //结果返回

                         }];
}

注意

你可以通过 jsonOption 字段来筛选有副歌片段、支持打分的音乐资源。jsonOption 字段的具体说明见 searchMusic[1/2] 及 searchMusic[2/2] 的 API 文档。

使用 RESTful API 获取

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

实现 HTTP 认证 RESTful API 仅支持 HTTPS 协议。发送请求时，你需要通过 Basic HTTP 认证，并将生成的凭证填入 HTTP 请求头部的 Authorization 字段。具体生成 Authorization 字段的方法请参考 HTTP 基本认证。
获取歌曲列表根据你的需求调用不同的 RESTful API 来获取歌曲列表、热门榜单等，调用说明及示例详见 API 文档。

3. 加载及播放版权音乐

成功获取版权音乐后，调用 loadMusic[1/2] 加载歌曲。该方法中你需要传入歌曲编号并进行歌曲加载配置。歌曲加载结果会通过 IMusicLoadStateListener 接口类下的回调通知你。在调用 loadMusic[1/2] 时，你需要传入下列参数：

songCode：歌曲编号，可参考步骤 2获取。如果你需要播放歌曲的副歌片段，需要先调用 getInternalSongCode 方法为该片段创建一个编号，作为该片段的唯一标识。当你获取到该片段的编号后，调用 loadMusic 并将获取到的副歌片段编号传入 songCode 参数来加载该副歌片段。
config：歌曲加载配置，包含下列参数：
- songIdentifier：歌曲的唯一标识。如果你使用的是自行维护的曲库，你需要传入该参数，并需确保唯一性。如果你使用的是声网提供的版权音乐，向 songCode 传参即可，此参数传空。
- mode：歌曲加载的模式，默认为加载歌曲及歌词。
- mainSingerUid：独唱者的用户 ID。
IMusicLoadStateListener：监听歌曲加载状态的协议。

信息

目前仅支持一次加载一首歌曲，请在一首歌曲加载完成后再加载下一首。

Objective-C

// 下列示例代码以独唱者为例，展示如何加载、播放版权音乐
// 歌曲加载成功后需要在 onMusicLoadSuccess 回调内调用 switchSingerRole 切换用户角色为独唱者，再调用 startSing 开始演唱
KTVSongConfiguration *songConfig = [[KTVSongConfiguration alloc] init];
// 同时加载歌曲和歌词
songCode.songIdentifier = songIdentifier;
songConfig.mode = KTVLoadMusicModeLoadMusicAndLrc;
songConfig.mainSingerUid = mainSingerUid;

// 歌曲加载失败的原因
- (void)onMusicLoadFailWithSongCode:(NSInteger)songCode reason:(enum KTVLoadSongFailReason)reason {
}

// 歌曲加载成功的回调，在此回调内调用 switchSingerRole 切换角色，调用 startSing 开始播放歌曲
- (void)onMusicLoadSuccessWithSongCode:(NSInteger)songCode lyricUrl:(NSString *_Nonnull)lyricUrl {
    // 切换角色
    [weakSelf.ktvApi
        switchSingerRoleWithNewRole:KTVSingRoleSoloSinger
                  onSwitchRoleState:^(KTVSwitchRoleState state, KTVSwitchRoleFailReason reason){
                      // 切换角色状态回调
                  }];
    // 开始播放歌曲
    [weakSelf.ktvApi startSingWithSongCode:songCode startPos:0];
}

[self.ktvApi loadMusicWithSongCode:songCode config:songConfig onMusicLoadStateListener:self];

// 歌曲加载进度回调
- (void)onMusicLoadProgressWithSongCode:(NSInteger)songCode
                                percent:(NSInteger)percent
                                 status:(AgoraMusicContentCenterPreloadStatus)status
                                    msg:(NSString *)msg
                               lyricUrl:(NSString *)lyricUrl {
}

如果你需要取消当前正在加载的版权音乐、或者清除已加载的缓存，可以调用 removeMusic 方法。

Objective-C

[self.ktvApi removeMusicWithSongCode:songCode];

API 参考

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

前提条件

实现流程

1. 初始化设置

2. 获取版权音乐

使用场景化 API 获取

使用 RESTful API 获取

3. 加载及播放版权音乐

API 参考

相关文档

前提条件

实现流程

1. 初始化设置

2. 获取版权音乐

使用场景化 API 获取

使用 RESTful API 获取

3. 加载及播放版权音乐

API 参考

相关文档

咨询电话

咨询电话

前提条件Copy Anchor Link

实现流程Copy Anchor Link

1. 初始化设置Copy Anchor Link

2. 获取版权音乐Copy Anchor Link

使用场景化 API 获取Copy Anchor Link

使用 RESTful API 获取Copy Anchor Link

3. 加载及播放版权音乐Copy Anchor Link

API 参考Copy Anchor Link

相关文档Copy Anchor Link

咨询电话

咨询电话

前提条件

实现流程

1. 初始化设置

2. 获取版权音乐

使用场景化 API 获取

使用 RESTful API 获取

3. 加载及播放版权音乐

API 参考

相关文档