获取版权音乐

  • iOS

更新时间

了解声网解决方案在不同平台上的获取版权音乐方式,包括接入流程、关键配置和平台差异。

声网提供 K 歌热门曲库,涵盖 20 多万首正版歌曲。本文介绍如何使用 KTV 场景化 API 加载版权音乐并进行播放。

注意

  • 在使用获取版权音乐前,请联系技术支持开通权限。
  • 本文仅适用于 K 歌场景化 API v4.0.0。

前提条件

  • 已参考集成 KTV API 并实现基本的在线 K 歌逻辑,详情请参考集成 KTV API。
  • 有效的声网项目、获取项目的 RTM Token,详情请参考开通服务。

信息

  • 加载版权音乐时声网使用 RTM Token 进行鉴权,不会产生云信令服务费用。
  • 你可以参考开通服务获取临时 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. 获取歌曲列表

你可以调用 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){
                             }];
}

注意

你可以通过 jsonOption 字段来筛选有副歌片段、支持打分的音乐资源。jsonOption 字段的具体说明见 searchMusic[1/2] 及 searchMusic[2/2] 的 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:

相关文档

这个页面有帮助吗?